feat: add sync context and operation state

src/Sync/SyncContext.php

@@ -0,0 +1,92 @@
+<?php
+/**
+ * Immutable sync operation context.
+ *
+ * @package WPContentSync
+ */
+
+namespace WPContentSync\Sync;
+
+final class SyncContext {
+	private const CONFLICT_STRATEGIES = array( 'last_write_wins', 'manual_review' );
+
+	private string $direction;
+	private string $operation_id;
+	private string $source_url;
+	private string $destination_url;
+	private string $conflict_strategy;
+
+	/** @var array<string, string> */
+	private array $url_mappings;
+
+	/**
+	 * @param array<string, string> $url_mappings URL mappings.
+	 */
+	private function __construct(
+		string $direction,
+		string $operation_id,
+		string $source_url,
+		string $destination_url,
+		string $conflict_strategy,
+		array $url_mappings
+	) {
+		$this->direction         = $direction;
+		$this->operation_id      = $operation_id;
+		$this->source_url        = $source_url;
+		$this->destination_url   = $destination_url;
+		$this->conflict_strategy = in_array( $conflict_strategy, self::CONFLICT_STRATEGIES, true ) ? $conflict_strategy : 'last_write_wins';
+		$this->url_mappings      = $url_mappings;
+	}
+
+	/**
+	 * @param array<string, mixed> $source            Source site metadata.
+	 * @param array<string, mixed> $destination       Destination site metadata.
+	 * @param string               $conflict_strategy Conflict strategy.
+	 * @param string               $operation_id      Operation ID.
+	 */
+	public static function forImport( array $source, array $destination, string $conflict_strategy, string $operation_id ): self {
+		$source_url      = esc_url_raw( (string) ( $source['site_url'] ?? '' ) );
+		$destination_url = esc_url_raw( (string) ( $destination['site_url'] ?? '' ) );
+		$url_mappings    = array();
+
+		if ( '' !== $source_url && '' !== $destination_url ) {
+			$url_mappings[ $source_url ] = $destination_url;
+		}
+
+		return new self(
+			'import',
+			sanitize_key( $operation_id ),
+			$source_url,
+			$destination_url,
+			$conflict_strategy,
+			$url_mappings
+		);
+	}
+
+	public function direction(): string {
+		return $this->direction;
+	}
+
+	public function operationId(): string {
+		return $this->operation_id;
+	}
+
+	public function sourceUrl(): string {
+		return $this->source_url;
+	}
+
+	public function destinationUrl(): string {
+		return $this->destination_url;
+	}
+
+	public function conflictStrategy(): string {
+		return $this->conflict_strategy;
+	}
+
+	/**
+	 * @return array<string, string>
+	 */
+	public function urlMappings(): array {
+		return $this->url_mappings;
+	}
+}

src/Sync/SyncOperationState.php

@@ -0,0 +1,78 @@
+<?php
+/**
+ * Immutable sync operation progress state.
+ *
+ * @package WPContentSync
+ */
+
+namespace WPContentSync\Sync;
+
+final class SyncOperationState {
+	private string $operation_id;
+	private string $status;
+	private string $current_bucket;
+	private int $processed;
+	private int $total;
+
+	private function __construct( string $operation_id, string $status, string $current_bucket, int $processed, int $total ) {
+		$this->operation_id   = sanitize_key( $operation_id );
+		$this->status         = sanitize_key( $status );
+		$this->current_bucket = sanitize_key( $current_bucket );
+		$this->processed      = max( 0, $processed );
+		$this->total          = max( 0, $total );
+	}
+
+	public static function running( string $operation_id, string $current_bucket, int $processed, int $total ): self {
+		return new self( $operation_id, 'running', $current_bucket, $processed, $total );
+	}
+
+	public static function completed( string $operation_id, int $processed, int $total ): self {
+		return new self( $operation_id, 'completed', '', $processed, $total );
+	}
+
+	/**
+	 * @param array<string, mixed> $data State data.
+	 */
+	public static function fromArray( array $data ): self {
+		return new self(
+			(string) ( $data['operation_id'] ?? '' ),
+			(string) ( $data['status'] ?? '' ),
+			(string) ( $data['current_bucket'] ?? '' ),
+			(int) ( $data['processed'] ?? 0 ),
+			(int) ( $data['total'] ?? 0 )
+		);
+	}
+
+	public function operationId(): string {
+		return $this->operation_id;
+	}
+
+	public function status(): string {
+		return $this->status;
+	}
+
+	public function currentBucket(): string {
+		return $this->current_bucket;
+	}
+
+	public function processed(): int {
+		return $this->processed;
+	}
+
+	public function total(): int {
+		return $this->total;
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	public function toArray(): array {
+		return array(
+			'operation_id'   => $this->operation_id,
+			'status'         => $this->status,
+			'current_bucket' => $this->current_bucket,
+			'processed'      => $this->processed,
+			'total'          => $this->total,
+		);
+	}
+}

src/Sync/SyncStateRepository.php

@@ -0,0 +1,38 @@
+<?php
+/**
+ * Sync operation state persistence.
+ *
+ * @package WPContentSync
+ */
+
+namespace WPContentSync\Sync;
+
+final class SyncStateRepository {
+	private const DEFAULT_EXPIRATION = 86400;
+
+	public function save( SyncOperationState $state ): void {
+		set_transient( $this->key( $state->operationId() ), $state->toArray(), $this->expiration() );
+	}
+
+	public function get( string $operation_id ): ?SyncOperationState {
+		$value = get_transient( $this->key( $operation_id ) );
+
+		if ( ! is_array( $value ) ) {
+			return null;
+		}
+
+		return SyncOperationState::fromArray( $value );
+	}
+
+	public function delete( string $operation_id ): void {
+		delete_transient( $this->key( $operation_id ) );
+	}
+
+	private function key( string $operation_id ): string {
+		return 'wpcs_sync_state_' . sanitize_key( $operation_id );
+	}
+
+	private function expiration(): int {
+		return defined( 'DAY_IN_SECONDS' ) ? (int) DAY_IN_SECONDS : self::DEFAULT_EXPIRATION;
+	}
+}