[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Providers\Models\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  use WordPress\AiClient\Common\AbstractEnum;
   8  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   9  use WordPress\AiClient\Providers\Models\Enums\OptionEnum;
  10  /**
  11   * Represents a supported configuration option for an AI model.
  12   *
  13   * This class defines an option that a model supports, including its name
  14   * and the values that are valid for that option.
  15   *
  16   * @since 0.1.0
  17   *
  18   * @phpstan-type SupportedOptionArrayShape array{
  19   *     name: string,
  20   *     supportedValues?: list<mixed>
  21   * }
  22   *
  23   * @extends AbstractDataTransferObject<SupportedOptionArrayShape>
  24   */
  25  class SupportedOption extends AbstractDataTransferObject
  26  {
  27      public const KEY_NAME = 'name';
  28      public const KEY_SUPPORTED_VALUES = 'supportedValues';
  29      /**
  30       * @var OptionEnum The option name.
  31       */
  32      protected OptionEnum $name;
  33      /**
  34       * @var list<mixed>|null The supported values for this option.
  35       */
  36      protected ?array $supportedValues;
  37      /**
  38       * Constructor.
  39       *
  40       * @since 0.1.0
  41       *
  42       * @param OptionEnum $name The option name.
  43       * @param list<mixed>|null $supportedValues The supported values for this option, or null if any value is supported.
  44       *
  45       * @throws InvalidArgumentException If supportedValues is not null and not a list.
  46       */
  47      public function __construct(OptionEnum $name, ?array $supportedValues = null)
  48      {
  49          if ($supportedValues !== null && !array_is_list($supportedValues)) {
  50              throw new InvalidArgumentException('Supported values must be a list array.');
  51          }
  52          $this->name = $name;
  53          $this->supportedValues = $supportedValues;
  54      }
  55      /**
  56       * Gets the option name.
  57       *
  58       * @since 0.1.0
  59       *
  60       * @return OptionEnum The option name.
  61       */
  62      public function getName(): OptionEnum
  63      {
  64          return $this->name;
  65      }
  66      /**
  67       * Checks if a value is supported for this option.
  68       *
  69       * @since 0.1.0
  70       *
  71       * @param mixed $value The value to check.
  72       * @return bool True if the value is supported, false otherwise.
  73       */
  74      public function isSupportedValue($value): bool
  75      {
  76          // If supportedValues is null, any value is supported
  77          if ($this->supportedValues === null) {
  78              return \true;
  79          }
  80          // If the value is an array, consider it a set (i.e. order doesn't matter).
  81          if (is_array($value)) {
  82              $normalizedValue = self::normalizeArrayForComparison($value);
  83              foreach ($this->supportedValues as $supportedValue) {
  84                  if (!is_array($supportedValue)) {
  85                      continue;
  86                  }
  87                  $normalizedSupported = self::normalizeArrayForComparison($supportedValue);
  88                  if ($normalizedValue === $normalizedSupported) {
  89                      return \true;
  90                  }
  91              }
  92              return \false;
  93          }
  94          $normalizedValue = self::normalizeValue($value);
  95          foreach ($this->supportedValues as $supportedValue) {
  96              if (self::normalizeValue($supportedValue) === $normalizedValue) {
  97                  return \true;
  98              }
  99          }
 100          return \false;
 101      }
 102      /**
 103       * Normalizes an AbstractEnum instance to its string value.
 104       *
 105       * This ensures comparisons work correctly even after deserialization
 106       * (e.g. Redis/Memcached object cache), where AbstractEnum singletons
 107       * are reconstructed as separate instances.
 108       *
 109       * @since 1.2.1
 110       *
 111       * @param mixed $value The value to normalize.
 112       * @return mixed The normalized value.
 113       */
 114      private static function normalizeValue($value)
 115      {
 116          if ($value instanceof AbstractEnum) {
 117              return $value->value;
 118          }
 119          return $value;
 120      }
 121      /**
 122       * Normalizes and sorts an array for comparison.
 123       *
 124       * Maps each element through normalizeValue() and sorts the result,
 125       * ensuring consistent comparison regardless of element order or
 126       * AbstractEnum instance identity.
 127       *
 128       * @since 1.2.1
 129       *
 130       * @param array<mixed> $items The array to normalize.
 131       * @return array<mixed> The normalized, sorted array.
 132       */
 133      private static function normalizeArrayForComparison(array $items): array
 134      {
 135          $normalized = array_map([self::class, 'normalizeValue'], $items);
 136          sort($normalized);
 137          return $normalized;
 138      }
 139      /**
 140       * Gets the supported values for this option.
 141       *
 142       * @since 0.1.0
 143       *
 144       * @return list<mixed>|null The supported values, or null if any value is supported.
 145       */
 146      public function getSupportedValues(): ?array
 147      {
 148          return $this->supportedValues;
 149      }
 150      /**
 151       * {@inheritDoc}
 152       *
 153       * @since 0.1.0
 154       */
 155      public static function getJsonSchema(): array
 156      {
 157          return ['type' => 'object', 'properties' => [self::KEY_NAME => ['type' => 'string', 'enum' => OptionEnum::getValues(), 'description' => 'The option name.'], self::KEY_SUPPORTED_VALUES => ['type' => 'array', 'items' => ['oneOf' => [['type' => 'string'], ['type' => 'number'], ['type' => 'boolean'], ['type' => 'null'], ['type' => 'array'], ['type' => 'object']]], 'description' => 'The supported values for this option.']], 'required' => [self::KEY_NAME]];
 158      }
 159      /**
 160       * {@inheritDoc}
 161       *
 162       * @since 0.1.0
 163       *
 164       * @return SupportedOptionArrayShape
 165       */
 166      public function toArray(): array
 167      {
 168          $data = [self::KEY_NAME => $this->name->value];
 169          if ($this->supportedValues !== null) {
 170              /** @var list<mixed> $supportedValues */
 171              $supportedValues = $this->supportedValues;
 172              $data[self::KEY_SUPPORTED_VALUES] = $supportedValues;
 173          }
 174          return $data;
 175      }
 176      /**
 177       * {@inheritDoc}
 178       *
 179       * @since 0.1.0
 180       */
 181      public static function fromArray(array $array): self
 182      {
 183          static::validateFromArrayData($array, [self::KEY_NAME]);
 184          return new self(OptionEnum::from($array[self::KEY_NAME]), $array[self::KEY_SUPPORTED_VALUES] ?? null);
 185      }
 186  }