<?php
/**
 * Database clean-up: the contract of one check.
 *
 * @package AdminPowerups
 */

namespace SmartWP\AdminPowerups\Modules\DatabaseCleanup;

defined( 'ABSPATH' ) || exit;

/**
 * One kind of leftover rows the Database clean-up tab can count, show and delete.
 *
 * The count and clean methods are resumable: they get the state they returned last time (an opaque
 * array the Runner keeps on the server; clients never send cursors) and stop when their time
 * budget runs out. Every clean() checks the orphan or age condition again inside its DELETE (or
 * right before each API call), so rows are never deleted just because an earlier SELECT picked
 * them.
 *
 * Add-ons add checks through the `apwc_database_cleanup_checks` filter; extend BaseCheck.
 *
 * @since 1.0.0
 */
interface Check {

	/**
	 * Unique ID: 1 to 64 characters of a-z, 0-9 and -.
	 *
	 * @since 1.0.0
	 * @return string
	 */
	public function id(): string;

	/**
	 * Group: `woocommerce`, `scheduled-actions` or `wordpress` (others show under WordPress).
	 *
	 * @since 1.0.0
	 * @return string
	 */
	public function group(): string;

	/**
	 * Short name.
	 *
	 * @since 1.0.0
	 * @return string
	 */
	public function label(): string;

	/**
	 * What the rows are, in one or two sentences.
	 *
	 * @since 1.0.0
	 * @return string
	 */
	public function description(): string;

	/**
	 * What deleting them means, shown before the clean is confirmed.
	 *
	 * @since 1.0.0
	 * @return string
	 */
	public function consequence(): string;

	/**
	 * DevGuard level of the clean: `safe`, `review` or `advanced` (unknown values count as advanced).
	 *
	 * @since 1.0.0
	 * @return string
	 */
	public function risk(): string;

	/**
	 * Extra capability the clean and the sample need (for example `edit_shop_orders`), or ''.
	 *
	 * @since 1.0.0
	 * @return string
	 */
	public function object_cap(): string;

	/**
	 * Why the check can't run here, or '' when it can.
	 *
	 * @since 1.0.0
	 * @return string
	 */
	public function unavailable(): string;

	/**
	 * Whether counting walks the table in chunks ("Slower to scan").
	 *
	 * @since 1.0.0
	 * @return bool
	 */
	public function slow(): bool;

	/**
	 * Tables the check reads and deletes from, first = the one its rows live in.
	 *
	 * @since 1.0.0
	 * @return string[]
	 */
	public function tables(): array;

	/**
	 * Age threshold in days, or null when the check has none.
	 *
	 * @since 1.0.0
	 * @return int|null
	 */
	public function threshold(): ?int;

	/**
	 * Whether the clean needs the "I have a recent backup" confirmation.
	 *
	 * @since 1.0.0
	 * @return bool
	 */
	public function requires_backup(): bool;

	/**
	 * Count rows, resumably.
	 *
	 * @since 1.0.0
	 * @param array<string, mixed> $state  State from the last call ([] to start).
	 * @param float                $budget Seconds to spend at most (roughly).
	 * @return array{count: int, done: bool, state: array<string, mixed>} `count` is the running
	 *         total (-1: can't be counted); `done` true when finished.
	 */
	public function count( array $state, float $budget ): array;

	/**
	 * A few example rows, already masked and cut (never secrets, session data or passwords).
	 *
	 * @since 1.0.0
	 * @param int $limit Rows (at most 10).
	 * @return array{columns: array<string, string>, rows: array<int, array<string, string>>}
	 */
	public function sample( int $limit = 10 ): array;

	/**
	 * Delete rows, resumably.
	 *
	 * @since 1.0.0
	 * @param array<string, mixed> $state  State from the last call ([] to start).
	 * @param int                  $batch  Rows per statement.
	 * @param float                $budget Seconds to spend at most (roughly).
	 * @return array{deleted: int, skipped: int, notes: array<string, int>, done: bool, state: array<string, mixed>, progress?: bool}
	 *         Optional `progress` true tells the weekly job a step that deleted nothing and kept
	 *         its state still moved on (otherwise such a step counts as "no progress").
	 */
	public function clean( array $state, int $batch, float $budget ): array;
}