feat: validates lists and improves type checking

Author: JasonTheAdams

src/Providers/DTO/ProviderModelsMetadata.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Providers\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 
@@ -36,7 +37,7 @@ class ProviderModelsMetadata extends AbstractDataValueObject
     protected ProviderMetadata $provider;
 
     /**
-     * @var ModelMetadata[] The available models.
+     * @var list<ModelMetadata> The available models.
      */
     protected array $models;
 
@@ -46,10 +47,16 @@ class ProviderModelsMetadata extends AbstractDataValueObject
      * @since n.e.x.t
      *
      * @param ProviderMetadata $provider The provider metadata.
-     * @param ModelMetadata[] $models The available models.
+     * @param list<ModelMetadata> $models The available models.
+     *
+     * @throws InvalidArgumentException If models is not a list.
      */
     public function __construct(ProviderMetadata $provider, array $models)
     {
+        if (!array_is_list($models)) {
+            throw new InvalidArgumentException('Models must be a list array.');
+        }
+
         $this->provider = $provider;
         $this->models = $models;
     }
@@ -71,7 +78,7 @@ public function getProvider(): ProviderMetadata
      *
      * @since n.e.x.t
      *
-     * @return ModelMetadata[] The available models.
+     * @return list<ModelMetadata> The available models.
      */
     public function getModels(): array
     {
@@ -108,7 +115,6 @@ public static function getJsonSchema(): array
      */
     public function toArray(): array
     {
-        /** @phpstan-ignore-next-line return.type (array_map doesn't guarantee list, validation will be added later) */
         return [
             self::KEY_PROVIDER => $this->provider->toArray(),
             self::KEY_MODELS => array_map(

src/Providers/Models/DTO/ModelConfig.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Models\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
 use WordPress\AiClient\Tools\DTO\Tool;
@@ -60,7 +61,7 @@ class ModelConfig extends AbstractDataValueObject
     public const KEY_CUSTOM_OPTIONS = 'customOptions';
 
     /**
-     * @var ModalityEnum[]|null Output modalities for the model.
+     * @var list<ModalityEnum>|null Output modalities for the model.
      */
     protected ?array $outputModalities = null;
 
@@ -95,7 +96,7 @@ class ModelConfig extends AbstractDataValueObject
     protected ?int $topK = null;
 
     /**
-     * @var string[]|null Stop sequences.
+     * @var list<string>|null Stop sequences.
      */
     protected ?array $stopSequences = null;
 
@@ -120,7 +121,7 @@ class ModelConfig extends AbstractDataValueObject
     protected ?int $topLogprobs = null;
 
     /**
-     * @var Tool[]|null Tools available to the model.
+     * @var list<Tool>|null Tools available to the model.
      */
     protected ?array $tools = null;
 
@@ -144,10 +145,16 @@ class ModelConfig extends AbstractDataValueObject
      *
      * @since n.e.x.t
      *
-     * @param ModalityEnum[] $outputModalities The output modalities.
+     * @param list<ModalityEnum> $outputModalities The output modalities.
+     *
+     * @throws InvalidArgumentException If the array is not a list.
      */
     public function setOutputModalities(array $outputModalities): void
     {
+        if (!array_is_list($outputModalities)) {
+            throw new InvalidArgumentException('Output modalities must be a list array.');
+        }
+
         $this->outputModalities = $outputModalities;
     }
 
@@ -156,7 +163,7 @@ public function setOutputModalities(array $outputModalities): void
      *
      * @since n.e.x.t
      *
-     * @return ModalityEnum[]|null The output modalities.
+     * @return list<ModalityEnum>|null The output modalities.
      */
     public function getOutputModalities(): ?array
     {
@@ -312,10 +319,16 @@ public function getTopK(): ?int
      *
      * @since n.e.x.t
      *
-     * @param string[] $stopSequences The stop sequences.
+     * @param list<string> $stopSequences The stop sequences.
+     *
+     * @throws InvalidArgumentException If the array is not a list.
      */
     public function setStopSequences(array $stopSequences): void
     {
+        if (!array_is_list($stopSequences)) {
+            throw new InvalidArgumentException('Stop sequences must be a list array.');
+        }
+
         $this->stopSequences = $stopSequences;
     }
 
@@ -324,7 +337,7 @@ public function setStopSequences(array $stopSequences): void
      *
      * @since n.e.x.t
      *
-     * @return string[]|null The stop sequences.
+     * @return list<string>|null The stop sequences.
      */
     public function getStopSequences(): ?array
     {
@@ -432,10 +445,16 @@ public function getTopLogprobs(): ?int
      *
      * @since n.e.x.t
      *
-     * @param Tool[] $tools The tools.
+     * @param list<Tool> $tools The tools.
+     *
+     * @throws InvalidArgumentException If the array is not a list.
      */
     public function setTools(array $tools): void
     {
+        if (!array_is_list($tools)) {
+            throw new InvalidArgumentException('Tools must be a list array.');
+        }
+
         $this->tools = $tools;
     }
 
@@ -444,7 +463,7 @@ public function setTools(array $tools): void
      *
      * @since n.e.x.t
      *
-     * @return Tool[]|null The tools.
+     * @return list<Tool>|null The tools.
      */
     public function getTools(): ?array
     {
@@ -721,7 +740,6 @@ static function (ModalityEnum $modality): string {
 
         $data[self::KEY_CUSTOM_OPTIONS] = $this->customOptions;
 
-        /** @phpstan-ignore-next-line return.type (array_map doesn't guarantee list, validation will be added later) */
         return $data;
     }
 

src/Providers/Models/DTO/ModelMetadata.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Models\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
 
@@ -44,12 +45,12 @@ class ModelMetadata extends AbstractDataValueObject
     protected string $name;
 
     /**
-     * @var CapabilityEnum[] The model's supported capabilities.
+     * @var list<CapabilityEnum> The model's supported capabilities.
      */
     protected array $supportedCapabilities;
 
     /**
-     * @var SupportedOption[] The model's supported configuration options.
+     * @var list<SupportedOption> The model's supported configuration options.
      */
     protected array $supportedOptions;
 
@@ -60,11 +61,21 @@ class ModelMetadata extends AbstractDataValueObject
      *
      * @param string $id The model's unique identifier.
      * @param string $name The model's display name.
-     * @param CapabilityEnum[] $supportedCapabilities The model's supported capabilities.
-     * @param SupportedOption[] $supportedOptions The model's supported configuration options.
+     * @param list<CapabilityEnum> $supportedCapabilities The model's supported capabilities.
+     * @param list<SupportedOption> $supportedOptions The model's supported configuration options.
+     *
+     * @throws InvalidArgumentException If arrays are not lists.
      */
     public function __construct(string $id, string $name, array $supportedCapabilities, array $supportedOptions)
     {
+        if (!array_is_list($supportedCapabilities)) {
+            throw new InvalidArgumentException('Supported capabilities must be a list array.');
+        }
+
+        if (!array_is_list($supportedOptions)) {
+            throw new InvalidArgumentException('Supported options must be a list array.');
+        }
+
         $this->id = $id;
         $this->name = $name;
         $this->supportedCapabilities = $supportedCapabilities;
@@ -100,7 +111,7 @@ public function getName(): string
      *
      * @since n.e.x.t
      *
-     * @return CapabilityEnum[] The supported capabilities.
+     * @return list<CapabilityEnum> The supported capabilities.
      */
     public function getSupportedCapabilities(): array
     {
@@ -112,7 +123,7 @@ public function getSupportedCapabilities(): array
      *
      * @since n.e.x.t
      *
-     * @return SupportedOption[] The supported options.
+     * @return list<SupportedOption> The supported options.
      */
     public function getSupportedOptions(): array
     {
@@ -164,7 +175,6 @@ public static function getJsonSchema(): array
      */
     public function toArray(): array
     {
-        /** @phpstan-ignore-next-line return.type (array_map doesn't guarantee list, validation will be added later) */
         return [
             self::KEY_ID => $this->id,
             self::KEY_NAME => $this->name,

src/Providers/Models/DTO/ModelRequirements.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Models\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
 
@@ -30,12 +31,12 @@ class ModelRequirements extends AbstractDataValueObject
     public const KEY_REQUIRED_OPTIONS = 'requiredOptions';
 
     /**
-     * @var CapabilityEnum[] The capabilities that the model must support.
+     * @var list<CapabilityEnum> The capabilities that the model must support.
      */
     protected array $requiredCapabilities;
 
     /**
-     * @var RequiredOption[] The options that the model must support with specific values.
+     * @var list<RequiredOption> The options that the model must support with specific values.
      */
     protected array $requiredOptions;
 
@@ -44,11 +45,21 @@ class ModelRequirements extends AbstractDataValueObject
      *
      * @since n.e.x.t
      *
-     * @param CapabilityEnum[] $requiredCapabilities The capabilities that the model must support.
-     * @param RequiredOption[] $requiredOptions The options that the model must support with specific values.
+     * @param list<CapabilityEnum> $requiredCapabilities The capabilities that the model must support.
+     * @param list<RequiredOption> $requiredOptions The options that the model must support with specific values.
+     *
+     * @throws InvalidArgumentException If arrays are not lists.
      */
     public function __construct(array $requiredCapabilities, array $requiredOptions)
     {
+        if (!array_is_list($requiredCapabilities)) {
+            throw new InvalidArgumentException('Required capabilities must be a list array.');
+        }
+
+        if (!array_is_list($requiredOptions)) {
+            throw new InvalidArgumentException('Required options must be a list array.');
+        }
+
         $this->requiredCapabilities = $requiredCapabilities;
         $this->requiredOptions = $requiredOptions;
     }
@@ -58,7 +69,7 @@ public function __construct(array $requiredCapabilities, array $requiredOptions)
      *
      * @since n.e.x.t
      *
-     * @return CapabilityEnum[] The required capabilities.
+     * @return list<CapabilityEnum> The required capabilities.
      */
     public function getRequiredCapabilities(): array
     {
@@ -70,7 +81,7 @@ public function getRequiredCapabilities(): array
      *
      * @since n.e.x.t
      *
-     * @return RequiredOption[] The required options.
+     * @return list<RequiredOption> The required options.
      */
     public function getRequiredOptions(): array
     {
@@ -114,7 +125,6 @@ public static function getJsonSchema(): array
      */
     public function toArray(): array
     {
-        /** @phpstan-ignore-next-line return.type (array_map doesn't guarantee list, validation will be added later) */
         return [
             self::KEY_REQUIRED_CAPABILITIES => array_map(
                 static fn(CapabilityEnum $capability): string => $capability->value,

src/Providers/Models/DTO/SupportedOption.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Models\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataValueObject;
 
 /**
@@ -32,7 +33,7 @@ class SupportedOption extends AbstractDataValueObject
     protected string $name;
 
     /**
-     * @var mixed[]|null The supported values for this option.
+     * @var list<mixed>|null The supported values for this option.
      */
     protected ?array $supportedValues;
 
@@ -42,10 +43,16 @@ class SupportedOption extends AbstractDataValueObject
      * @since n.e.x.t
      *
      * @param string $name The option name.
-     * @param mixed[]|null $supportedValues The supported values for this option, or null if any value is supported.
+     * @param list<mixed>|null $supportedValues The supported values for this option, or null if any value is supported.
+     *
+     * @throws InvalidArgumentException If supportedValues is not null and not a list.
      */
     public function __construct(string $name, ?array $supportedValues = null)
     {
+        if ($supportedValues !== null && !array_is_list($supportedValues)) {
+            throw new InvalidArgumentException('Supported values must be a list array.');
+        }
+
         $this->name = $name;
         $this->supportedValues = $supportedValues;
     }
@@ -85,7 +92,7 @@ public function isSupportedValue($value): bool
      *
      * @since n.e.x.t
      *
-     * @return mixed[]|null The supported values, or null if any value is supported.
+     * @return list<mixed>|null The supported values, or null if any value is supported.
      */
     public function getSupportedValues(): ?array
     {
@@ -139,10 +146,11 @@ public function toArray(): array
         ];
 
         if ($this->supportedValues !== null) {
-            $data[self::KEY_SUPPORTED_VALUES] = $this->supportedValues;
+            /** @var list<mixed> $supportedValues */
+            $supportedValues = $this->supportedValues;
+            $data[self::KEY_SUPPORTED_VALUES] = $supportedValues;
         }
 
-        /** @phpstan-ignore-next-line return.type (array doesn't guarantee list, validation will be added later) */
         return $data;
     }