[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Operations\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  use WordPress\AiClient\Operations\Contracts\OperationInterface;
   8  use WordPress\AiClient\Operations\Enums\OperationStateEnum;
   9  use WordPress\AiClient\Results\DTO\GenerativeAiResult;
  10  /**
  11   * Represents a long-running generative AI operation.
  12   *
  13   * This DTO tracks the progress of generative AI tasks that may not complete
  14   * immediately, providing access to the result once available.
  15   *
  16   * @since 0.1.0
  17   *
  18   * @phpstan-import-type GenerativeAiResultArrayShape from GenerativeAiResult
  19   *
  20   * @phpstan-type GenerativeAiOperationArrayShape array{id: string, state: string, result?: GenerativeAiResultArrayShape}
  21   *
  22   * @extends AbstractDataTransferObject<GenerativeAiOperationArrayShape>
  23   */
  24  class GenerativeAiOperation extends AbstractDataTransferObject implements OperationInterface
  25  {
  26      public const KEY_ID = 'id';
  27      public const KEY_STATE = 'state';
  28      public const KEY_RESULT = 'result';
  29      /**
  30       * @var string Unique identifier for this operation.
  31       */
  32      private string $id;
  33      /**
  34       * @var OperationStateEnum The current state of the operation.
  35       */
  36      private OperationStateEnum $state;
  37      /**
  38       * @var GenerativeAiResult|null The result once the operation completes.
  39       */
  40      private ?GenerativeAiResult $result;
  41      /**
  42       * Constructor.
  43       *
  44       * @since 0.1.0
  45       *
  46       * @param string $id Unique identifier for this operation.
  47       * @param OperationStateEnum $state The current state of the operation.
  48       * @param GenerativeAiResult|null $result The result once the operation completes.
  49       */
  50      public function __construct(string $id, OperationStateEnum $state, ?GenerativeAiResult $result = null)
  51      {
  52          $this->id = $id;
  53          $this->state = $state;
  54          $this->result = $result;
  55      }
  56      /**
  57       * Creates a deep clone of this operation.
  58       *
  59       * Clones the result object if present to ensure the cloned
  60       * operation is independent of the original.
  61       * The state enum is immutable and can be safely shared.
  62       *
  63       * @since 0.4.2
  64       */
  65      public function __clone()
  66      {
  67          // Clone the result if present (GenerativeAiResult has __clone)
  68          if ($this->result !== null) {
  69              $this->result = clone $this->result;
  70          }
  71          // Note: $state is an immutable enum and can be safely shared
  72      }
  73      /**
  74       * {@inheritDoc}
  75       *
  76       * @since 0.1.0
  77       */
  78      public function getId(): string
  79      {
  80          return $this->id;
  81      }
  82      /**
  83       * {@inheritDoc}
  84       *
  85       * @since 0.1.0
  86       */
  87      public function getState(): OperationStateEnum
  88      {
  89          return $this->state;
  90      }
  91      /**
  92       * Gets the operation result.
  93       *
  94       * @since 0.1.0
  95       *
  96       * @return GenerativeAiResult|null The result or null if not yet complete.
  97       */
  98      public function getResult(): ?GenerativeAiResult
  99      {
 100          return $this->result;
 101      }
 102      /**
 103       * {@inheritDoc}
 104       *
 105       * @since 0.1.0
 106       */
 107      public static function getJsonSchema(): array
 108      {
 109          return ['oneOf' => [
 110              // Succeeded state - has result
 111              ['type' => 'object', 'properties' => [self::KEY_ID => ['type' => 'string', 'description' => 'Unique identifier for this operation.'], self::KEY_STATE => ['type' => 'string', 'const' => OperationStateEnum::succeeded()->value], self::KEY_RESULT => GenerativeAiResult::getJsonSchema()], 'required' => [self::KEY_ID, self::KEY_STATE, self::KEY_RESULT], 'additionalProperties' => \false],
 112              // All other states - no result
 113              ['type' => 'object', 'properties' => [self::KEY_ID => ['type' => 'string', 'description' => 'Unique identifier for this operation.'], self::KEY_STATE => ['type' => 'string', 'enum' => [OperationStateEnum::starting()->value, OperationStateEnum::processing()->value, OperationStateEnum::failed()->value, OperationStateEnum::canceled()->value], 'description' => 'The current state of the operation.']], 'required' => [self::KEY_ID, self::KEY_STATE], 'additionalProperties' => \false],
 114          ]];
 115      }
 116      /**
 117       * {@inheritDoc}
 118       *
 119       * @since 0.1.0
 120       *
 121       * @return GenerativeAiOperationArrayShape
 122       */
 123      public function toArray(): array
 124      {
 125          $data = [self::KEY_ID => $this->id, self::KEY_STATE => $this->state->value];
 126          if ($this->result !== null) {
 127              $data[self::KEY_RESULT] = $this->result->toArray();
 128          }
 129          return $data;
 130      }
 131      /**
 132       * {@inheritDoc}
 133       *
 134       * @since 0.1.0
 135       */
 136      public static function fromArray(array $array): self
 137      {
 138          static::validateFromArrayData($array, [self::KEY_ID, self::KEY_STATE]);
 139          $state = OperationStateEnum::from($array[self::KEY_STATE]);
 140          if ($state->isSucceeded()) {
 141              // If the operation has succeeded, it must have a result
 142              static::validateFromArrayData($array, [self::KEY_RESULT]);
 143          }
 144          $result = null;
 145          if (isset($array[self::KEY_RESULT])) {
 146              $result = GenerativeAiResult::fromArray($array[self::KEY_RESULT]);
 147          }
 148          return new self($array[self::KEY_ID], $state, $result);
 149      }
 150  }