Merge pull request #33 from WordPress/array-list-polyfill

Author: JasonTheAdams

CONTRIBUTING.md

@@ -23,20 +23,24 @@ The following naming conventions must be followed for consistency and autoloadin
 All code must be properly documented with PHPDoc blocks following these standards:
 
 ### General rules
+
 - All descriptions must end with a period.
 - Use `@since n.e.x.t` for new code (will be replaced with actual version on release).
 - Place `@since` tags below the description and above `@param` tags, with blank comment lines around it.
 
 ### Method documentation
+
 - Method descriptions must start with a third-person verb (e.g., "Creates", "Returns", "Checks").
 - Exceptions: Constructors and magic methods may use different phrasing.
 - All `@return` annotations must include a description.
 
 ### Interface implementations
+
 - Use `{@inheritDoc}` instead of duplicating descriptions when implementing interface methods.
 - Only provide a unique description if it adds value beyond the interface documentation.
 
 ### Example
+
 ```php
 /**
  * Class for handling user authentication requests.
@@ -61,6 +65,12 @@ class AuthHandler
 }
 ```
 
+### Array Lists
+
+When an array is a list — that is, an array where the keys are sequential, starting at 0 — use the `list` generic type within the docblock. For example, a parameter that is a list of strings would be documented as `@param list<string> $variable`.
+
+Note that `list<string>` and `string[]` _are not_ the same. The latter is an alias for `array<int, string>` which does not enforce that the keys are sequential. That particular syntax, therefore, will rarely be used.
+
 ## PHP Compatibility
 
 All code must be backward compatible with PHP 7.4, which is the minimum required PHP version for this project.

composer.json

@@ -34,7 +34,10 @@
     "autoload": {
         "psr-4": {
             "WordPress\\AiClient\\": "src/"
-        }
+        },
+        "files": [
+            "src/polyfills.php"
+        ]
     },
     "autoload-dev": {
         "psr-4": {

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,