Merge branch 'dto-serlialization' into extender-dtos

Author: JasonTheAdams

src/Common/AbstractDataValueObject.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Common;
 
+use InvalidArgumentException;
 use JsonSerializable;
 use stdClass;
 use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
@@ -31,6 +32,36 @@ abstract class AbstractDataValueObject implements
     WithJsonSchemaInterface,
     JsonSerializable
 {
+    /**
+     * Validates that required keys exist in the array data.
+     *
+     * @since n.e.x.t
+     *
+     * @param TArrayShape $data The array data to validate.
+     * @param string[] $requiredKeys The keys that must be present.
+     * @throws InvalidArgumentException If any required key is missing.
+     */
+    protected static function validateFromArrayData(array $data, array $requiredKeys): void
+    {
+        $missingKeys = [];
+
+        foreach ($requiredKeys as $key) {
+            if (!isset($data[$key])) {
+                $missingKeys[] = $key;
+            }
+        }
+
+        if (!empty($missingKeys)) {
+            throw new InvalidArgumentException(
+                sprintf(
+                    '%s::fromArray() missing required keys: %s',
+                    static::class,
+                    implode(', ', $missingKeys)
+                )
+            );
+        }
+    }
+
     /**
      * Converts the object to a JSON-serializable format.
      *

src/Files/DTO/File.php

@@ -423,6 +423,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): File
     {
+        static::validateFromArrayData($array, ['fileType']);
+
         // Check which properties are set to determine how to construct the File
         $mimeType = $array['mimeType'] ?? null;
 

src/Messages/DTO/Message.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
 
@@ -126,6 +127,8 @@ public function toArray(): array
      */
     final public static function fromArray(array $array): Message
     {
+        static::validateFromArrayData($array, ['role', 'parts']);
+
         $role = MessageRoleEnum::from($array['role']);
         $partsData = $array['parts'];
         $parts = array_map(function (array $partData) {

src/Messages/DTO/MessagePart.php

@@ -255,6 +255,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): MessagePart
     {
+        static::validateFromArrayData($array, ['type']);
+
         // Check which properties are set to determine how to construct the MessagePart
         if (isset($array['text'])) {
             return new self($array['text']);

src/Operations/DTO/GenerativeAiOperation.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Operations\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Operations\Contracts\OperationInterface;
 use WordPress\AiClient\Operations\Enums\OperationStateEnum;
@@ -168,6 +169,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): GenerativeAiOperation
     {
+        static::validateFromArrayData($array, ['id', 'state']);
+
         $state = OperationStateEnum::from($array['state']);
         $result = null;
         if (isset($array['result'])) {

src/Results/DTO/Candidate.php

@@ -146,6 +146,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): Candidate
     {
+        static::validateFromArrayData($array, ['message', 'finishReason', 'tokenCount']);
+
         $messageData = $array['message'];
 
         return new self(

src/Results/DTO/GenerativeAiResult.php

@@ -417,6 +417,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): GenerativeAiResult
     {
+        static::validateFromArrayData($array, ['id', 'candidates', 'tokenUsage']);
+
         $candidates = array_map(fn(array $candidateData) => Candidate::fromArray($candidateData), $array['candidates']);
 
         return new self(

src/Results/DTO/TokenUsage.php

@@ -141,6 +141,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): TokenUsage
     {
+        static::validateFromArrayData($array, ['promptTokens', 'completionTokens', 'totalTokens']);
+
         return new self(
             $array['promptTokens'],
             $array['completionTokens'],

src/Tools/DTO/FunctionDeclaration.php

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Tools\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataValueObject;
 
 /**
@@ -142,6 +143,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): FunctionDeclaration
     {
+        static::validateFromArrayData($array, ['name', 'description']);
+
         return new self(
             $array['name'],
             $array['description'],

src/Tools/DTO/FunctionResponse.php

@@ -137,6 +137,8 @@ public function toArray(): array
      */
     public static function fromArray(array $array): FunctionResponse
     {
+        static::validateFromArrayData($array, ['id', 'name', 'response']);
+
         return new self(
             $array['id'],
             $array['name'],