* @copyright 2026 webhead GmbH */ declare( strict_types=1 ); namespace Webhead\WP\SearchCloud\Database\Tables; use Webhead\WP\SearchCloud\Dependencies\Webhead\WP\Framework\Database\Blueprint; use Webhead\WP\SearchCloud\Dependencies\Webhead\WP\Framework\Database\Table; use Webhead\WP\SearchCloud\Enums\Sync_Status; use Webhead\WP\SearchCloud\Enums\Sync_Trigger; defined( 'ABSPATH' ) || exit; /** * @since 1.0.0 */ final class Sync_Runs_Table extends Table { protected function get_table_name(): string { return 'searcio_sync_runs'; } /** * Schema: * | Column | Type | * | --------------- | ------------ | * | id | BIGINT(20) | * | status | VARCHAR(20) | queued|running|paused|completed|failed|cancelled * | trigger_type | VARCHAR(20) | manual|scheduled|incremental * | triggered_by | BIGINT(20) | user id, null for scheduled/incremental * | is_force | TINYINT(1) | ignore dirty hashes when set * | phase | VARCHAR(40) | current post type / "prune" / "done" * | cursor_state | TEXT | resumable cursor (JSON) * | control | VARCHAR(20) | between-batch signal: ''|pause|cancel * * `is_force`/`cursor_state` avoid the reserved SQL words FORCE/CURSOR, like * `trigger_type` avoids TRIGGER; the REST payload exposes them as `force`/`cursor`. * | total_estimated | INT | * | processed | INT | * | pushed | INT | * | skipped | INT | * | language_skipped| INT | skipped by the language restriction * | deleted | INT | * | failed_count | INT | * | started_at | DATETIME | * | finished_at | DATETIME | * | last_error | TEXT | * | created_at | TIMESTAMP | * | updated_at | TIMESTAMP | */ protected function get_table_schema( Blueprint $table ): void { $table->bigint( 'id' )->unsigned()->auto_increment()->primary(); $table->string( 'status', 20 )->not_nullable()->default_to( 'queued' ); $table->string( 'trigger_type', 20 )->not_nullable()->default_to( 'manual' ); $table->bigint( 'triggered_by' )->unsigned()->nullable(); $table->boolean( 'is_force' )->default_to( '0' ); $table->string( 'phase', 40 )->nullable(); $table->text( 'cursor_state' )->nullable(); $table->string( 'control', 20 )->not_nullable()->default_to( '' ); $table->integer( 'total_estimated' )->default_to( '0' ); $table->integer( 'processed' )->default_to( '0' ); $table->integer( 'pushed' )->default_to( '0' ); $table->integer( 'skipped' )->default_to( '0' ); $table->integer( 'language_skipped' )->default_to( '0' ); $table->integer( 'deleted' )->default_to( '0' ); $table->integer( 'failed_count' )->default_to( '0' ); $table->datetime( 'started_at' )->nullable(); $table->datetime( 'finished_at' )->nullable(); $table->text( 'last_error' )->nullable(); $table->timestamps(); $table->index( 'status', [ 'status' ] ); $table->index( 'trigger_type', [ 'trigger_type' ] ); $table->index( 'created_at', [ 'created_at' ] ); } protected function get_default_values(): array { return []; } public function get_version(): string { return '1.1'; } /** Columns allowed as a history sort key (defends the order_by input). */ private const SORTABLE = [ 'id', 'status', 'trigger_type', 'processed', 'pushed', 'created_at', 'finished_at' ]; /** * @param array $data */ public function insert_row( array $data ): int { // Not `$wpdb->insert_id` after insert(): the write invalidates the // table's cache group, which can insert an option row of its own, and // `insert_id` is then that row's. $id = $this->insert_get_id( $data ); return false === $id ? 0 : $id; } /** * @param array $data */ public function update_row( int $id, array $data ): void { $this->update( $data, [ 'id' => $id ] ); } /** * @return array|null */ public function find_row( int $id ): ?array { $row = $this->fresh_query()->where( 'id', $id )->first(); return $this->row_or_null( $row ); } /** * @return array|null */ public function active_row(): ?array { $row = $this->fresh_query() ->where_in( 'status', Sync_Status::active_values() ) ->order_by_desc( 'id' ) ->first(); return $this->row_or_null( $row ); } /** * Fresh read of just the between-batch control signal for a run. */ public function read_control( int $id ): string { $value = $this->fresh_query()->where( 'id', $id )->value( 'control' ); return is_string( $value ) ? $value : ''; } /** * Filtered, sorted, paginated history slice plus the total matching count. * * @param array $args * @return array{items:array>,total:int} */ public function query_history( array $args ): array { $per_page = max( 1, min( 100, (int) ( $args['per_page'] ?? 20 ) ) ); $page = max( 1, (int) ( $args['page'] ?? 1 ) ); $order_by = in_array( $args['order_by'] ?? '', self::SORTABLE, true ) ? (string) $args['order_by'] : 'id'; $order = strtolower( (string) ( $args['order'] ?? 'desc' ) ) === 'asc' ? 'asc' : 'desc'; $total = (int) $this->apply_filters( $this->fresh_query(), $args )->count(); $items = $this->apply_filters( $this->fresh_query(), $args ) ->order_by( $order_by, $order ) ->for_page( $page, $per_page ) ->get(); return [ 'items' => is_array( $items ) ? $items : [], 'total' => $total, ]; } public function delete_row( int $id ): bool { return false !== $this->delete( [ 'id' => $id ] ); } /** * Remove every finished (non-active) row. Returns the number deleted. */ public function clear_finished(): int { $deleted = 0; foreach ( Sync_Status::finished_values() as $status ) { $result = $this->delete( [ 'status' => $status ] ); if ( false !== $result ) { $deleted += (int) $result; } } return $deleted; } /** * Retention: delete finished rows created before the cutoff. Active rows are * inherently excluded because only finished statuses are matched. */ public function purge_older_than( string $cutoff_gmt ): int { $statuses = Sync_Status::finished_values(); if ( [] === $statuses ) { return 0; } /* * Written out rather than passed to `delete()` with a `'created_at <'` * operator key: that routes into the query builder, whose bindings reach * `wpdb::prepare()` in a form it rejects ("must have a placeholder"), so * the DELETE never ran and history grew without bound. Comparison * operators here stay on an explicitly prepared statement. */ $connection = $this->get_connection(); $result = $connection->query( $connection->prepare( 'DELETE FROM %i WHERE `status` IN (' . implode( ', ', array_fill( 0, count( $statuses ), '%s' ) ) . ') AND `created_at` < %s', [ $this->get_table_name_with_prefix(), ...$statuses, $cutoff_gmt ] ) ); if ( false === $result ) { return 0; } $this->cache_manager?->invalidate_group( $this->cache_group ); return (int) $result; } /** * @param \Webhead\WP\SearchCloud\Dependencies\Webhead\WP\Framework\Database\Query\Builder $query * @param array $args */ private function apply_filters( $query, array $args ) { if ( ! empty( $args['status'] ) && null !== Sync_Status::tryFrom( (string) $args['status'] ) ) { $query->where( 'status', (string) $args['status'] ); } if ( ! empty( $args['trigger'] ) && null !== Sync_Trigger::tryFrom( (string) $args['trigger'] ) ) { $query->where( 'trigger_type', (string) $args['trigger'] ); } if ( ! empty( $args['date_after'] ) ) { $query->where( 'created_at', '>=', (string) $args['date_after'] ); } if ( ! empty( $args['date_before'] ) ) { $query->where( 'created_at', '<=', (string) $args['date_before'] ); } return $query; } /** * @param mixed $row * @return array|null */ private function row_or_null( $row ): ?array { if ( ! is_array( $row ) || ! isset( $row['id'] ) ) { return null; } return $row; } }