feat: adds validation and improves RequiredOption description

Author: JasonTheAdams

src/Providers/DTO/ProviderModelsMetadata.php

@@ -123,6 +123,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): self
     {
+        static::validateFromArrayData($array, [self::KEY_PROVIDER, self::KEY_MODELS]);
+
         return new self(
             ProviderMetadata::fromArray($array[self::KEY_PROVIDER]),
             array_map(

src/Providers/Models/DTO/ModelMetadata.php

@@ -185,6 +185,13 @@ public function toArray(): array
      */
     public static function fromArray(array $array): self
     {
+        static::validateFromArrayData($array, [
+            self::KEY_ID,
+            self::KEY_NAME,
+            self::KEY_SUPPORTED_CAPABILITIES,
+            self::KEY_SUPPORTED_OPTIONS,
+        ]);
+
         return new self(
             $array[self::KEY_ID],
             $array[self::KEY_NAME],

src/Providers/Models/DTO/ModelRequirements.php

@@ -8,10 +8,10 @@
 use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
 
 /**
- * Represents requirements for selecting an AI model.
+ * Represents requirements that implementing code has for AI model selection.
  *
- * This class defines the capabilities and options that are required
- * when selecting a model for a specific task.
+ * This class defines the capabilities and options that a model must support
+ * in order to be considered suitable for the implementing code's needs.
  *
  * @since n.e.x.t
  *
@@ -30,12 +30,12 @@ class ModelRequirements extends AbstractDataValueObject
     public const KEY_REQUIRED_OPTIONS = 'requiredOptions';
 
     /**
-     * @var CapabilityEnum[] The required capabilities.
+     * @var CapabilityEnum[] The capabilities that the model must support.
      */
     protected array $requiredCapabilities;
 
     /**
-     * @var RequiredOption[] The required options.
+     * @var RequiredOption[] The options that the model must support with specific values.
      */
     protected array $requiredOptions;
 
@@ -44,8 +44,8 @@ class ModelRequirements extends AbstractDataValueObject
      *
      * @since n.e.x.t
      *
-     * @param CapabilityEnum[] $requiredCapabilities The required capabilities.
-     * @param RequiredOption[] $requiredOptions The required options.
+     * @param CapabilityEnum[] $requiredCapabilities The capabilities that the model must support.
+     * @param RequiredOption[] $requiredOptions The options that the model must support with specific values.
      */
     public function __construct(array $requiredCapabilities, array $requiredOptions)
     {
@@ -54,7 +54,7 @@ public function __construct(array $requiredCapabilities, array $requiredOptions)
     }
 
     /**
-     * Gets the required capabilities.
+     * Gets the capabilities that the model must support.
      *
      * @since n.e.x.t
      *
@@ -66,7 +66,7 @@ public function getRequiredCapabilities(): array
     }
 
     /**
-     * Gets the required options.
+     * Gets the options that the model must support with specific values.
      *
      * @since n.e.x.t
      *
@@ -93,12 +93,12 @@ public static function getJsonSchema(): array
                         'type' => 'string',
                         'enum' => CapabilityEnum::getValues(),
                     ],
-                    'description' => 'The required capabilities.',
+                    'description' => 'The capabilities that the model must support.',
                 ],
                 self::KEY_REQUIRED_OPTIONS => [
                     'type' => 'array',
                     'items' => RequiredOption::getJsonSchema(),
-                    'description' => 'The required options.',
+                    'description' => 'The options that the model must support with specific values.',
                 ],
             ],
             'required' => [self::KEY_REQUIRED_CAPABILITIES, self::KEY_REQUIRED_OPTIONS],
@@ -133,6 +133,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): self
     {
+        static::validateFromArrayData($array, [self::KEY_REQUIRED_CAPABILITIES, self::KEY_REQUIRED_OPTIONS]);
+
         return new self(
             array_map(
                 static fn(string $capability): CapabilityEnum => CapabilityEnum::from($capability),

src/Providers/Models/DTO/RequiredOption.php

@@ -7,10 +7,10 @@
 use WordPress\AiClient\Common\AbstractDataValueObject;
 
 /**
- * Represents a required configuration option for an AI model.
+ * Represents an option that the implementing code requires the model to support.
  *
- * This class defines an option that must be set when using a model,
- * including its name and the required value.
+ * This class defines an option that the model must support with a specific value
+ * for it to be considered suitable for the implementing code's requirements.
  *
  * @since n.e.x.t
  *
@@ -32,7 +32,7 @@ class RequiredOption extends AbstractDataValueObject
     protected string $name;
 
     /**
-     * @var mixed The required value.
+     * @var mixed The value that the model must support for this option.
      */
     protected $value;
 
@@ -42,7 +42,7 @@ class RequiredOption extends AbstractDataValueObject
      * @since n.e.x.t
      *
      * @param string $name The option name.
-     * @param mixed $value The required value.
+     * @param mixed $value The value that the model must support for this option.
      */
     public function __construct(string $name, $value)
     {
@@ -63,11 +63,11 @@ public function getName(): string
     }
 
     /**
-     * Gets the required value.
+     * Gets the value that the model must support for this option.
      *
      * @since n.e.x.t
      *
-     * @return mixed The required value.
+     * @return mixed The value that the model must support.
      */
     public function getValue()
     {
@@ -97,7 +97,7 @@ public static function getJsonSchema(): array
                         ['type' => 'array'],
                         ['type' => 'object'],
                     ],
-                    'description' => 'The required value.',
+                    'description' => 'The value that the model must support for this option.',
                 ],
             ],
             'required' => [self::KEY_NAME, self::KEY_VALUE],
@@ -126,6 +126,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): self
     {
+        static::validateFromArrayData($array, [self::KEY_NAME, self::KEY_VALUE]);
+
         return new self(
             $array[self::KEY_NAME],
             $array[self::KEY_VALUE]

src/Providers/Models/DTO/SupportedOption.php

@@ -142,6 +142,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): self
     {
+        static::validateFromArrayData($array, [self::KEY_NAME, self::KEY_SUPPORTED_VALUES]);
+
         return new self(
             $array[self::KEY_NAME],
             $array[self::KEY_SUPPORTED_VALUES]