Adds DTO array transformation and JSON serialization

src/Common/AbstractDataValueObject.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Common;
+
+use JsonSerializable;
+use stdClass;
+use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
+
+/**
+ * Abstract base class for all Data Value Objects in the AI Client.
+ *
+ * This abstract class consolidates the common functionality needed by all
+ * data transfer objects:
+ * - Array transformation for data manipulation
+ * - JSON schema support for validation and documentation
+ * - JSON serialization with proper empty object handling
+ *
+ * All DTOs in the AI Client should extend this class to ensure
+ * consistent behavior across the codebase.
+ *
+ * @since n.e.x.t
+ *
+ * @template TArrayShape of array<string, mixed>
+ * @implements WithArrayTransformationInterface<TArrayShape>
+ */
+abstract class AbstractDataValueObject implements
+    WithArrayTransformationInterface,
+    WithJsonSchemaInterface,
+    JsonSerializable
+{
+    /**
+     * Converts the object to a JSON-serializable format.
+     *
+     * This method uses the toArray() method and then processes the result
+     * based on the JSON schema to ensure proper object representation for
+     * empty arrays.
+     *
+     * @since n.e.x.t
+     *
+     * @return mixed The JSON-serializable representation.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+        $data = $this->toArray();
+        $schema = static::getJsonSchema();
+
+        return $this->convertEmptyArraysToObjects($data, $schema);
+    }
+
+    /**
+     * Recursively converts empty arrays to stdClass objects where the schema expects objects.
+     *
+     * @since n.e.x.t
+     *
+     * @param mixed $data The data to process.
+     * @param array<mixed, mixed> $schema The JSON schema for the data.
+     * @return mixed The processed data.
+     */
+    private function convertEmptyArraysToObjects($data, array $schema)
+    {
+        // If data is an empty array and schema expects object, convert to stdClass
+        if (is_array($data) && empty($data) && isset($schema['type']) && $schema['type'] === 'object') {
+            return new stdClass();
+        }
+
+        // If data is an array with content, recursively process nested structures
+        if (is_array($data)) {
+            // Handle object properties
+            if (isset($schema['properties']) && is_array($schema['properties'])) {
+                foreach ($data as $key => $value) {
+                    if (isset($schema['properties'][$key]) && is_array($schema['properties'][$key])) {
+                        $data[$key] = $this->convertEmptyArraysToObjects($value, $schema['properties'][$key]);
+                    }
+                }
+            }
+
+            // Handle array items
+            if (isset($schema['items']) && is_array($schema['items'])) {
+                foreach ($data as $index => $item) {
+                    $data[$index] = $this->convertEmptyArraysToObjects($item, $schema['items']);
+                }
+            }
+
+            // Handle oneOf schemas - just use the first one
+            if (isset($schema['oneOf']) && is_array($schema['oneOf'])) {
+                foreach ($schema['oneOf'] as $possibleSchema) {
+                    if (is_array($possibleSchema)) {
+                        return $this->convertEmptyArraysToObjects($data, $possibleSchema);
+                    }
+                }
+            }
+        }
+
+        return $data;
+    }
+}

src/Common/Contracts/WithArrayTransformationInterface.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Common\Contracts;
+
+/**
+ * Interface for objects that support array transformation.
+ *
+ * @since 1.0.0
+ *
+ * @template TArrayShape of array<string, mixed>
+ */
+interface WithArrayTransformationInterface
+{
+    /**
+     * Converts the object to an array representation.
+     *
+     * @since 1.0.0
+     *
+     * @return TArrayShape The array representation.
+     */
+    public function toArray(): array;
+
+    /**
+     * Creates an instance from array data.
+     *
+     * @since 1.0.0
+     *
+     * @param TArrayShape $array The array data.
+     * @return static The created instance.
+     */
+    public static function fromArray(array $array);
+}

src/Files/DTO/File.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Files\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\ValueObjects\MimeType;
 
@@ -15,8 +15,17 @@
  * and handles them appropriately.
  *
  * @since n.e.x.t
+ *
+ * @phpstan-type FileArrayShape array{
+ *     fileType: string,
+ *     url?: string,
+ *     mimeType?: string,
+ *     base64Data?: string
+ * }
+ *
+ * @extends AbstractDataValueObject<FileArrayShape>
  */
-class File implements WithJsonSchemaInterface
+final class File extends AbstractDataValueObject
 {
     /**
      * @var MimeType The MIME type of the file.
@@ -377,4 +386,49 @@ public static function getJsonSchema(): array
             ],
         ];
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     *
+     * @return FileArrayShape
+     */
+    public function toArray(): array
+    {
+        $data = [
+            'fileType' => $this->fileType->value,
+            'mimeType' => $this->getMimeType(),
+        ];
+
+        if ($this->fileType->isRemote() && $this->url !== null) {
+            $data['url'] = $this->url;
+        } elseif (!$this->fileType->isRemote() && $this->base64Data !== null) {
+            $data['base64Data'] = $this->base64Data;
+        }
+
+        return $data;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    public static function fromArray(array $array): File
+    {
+        $fileType = FileTypeEnum::from($array['fileType']);
+
+        if ($fileType->isRemote()) {
+            if (!isset($array['url']) || !isset($array['mimeType'])) {
+                throw new \InvalidArgumentException('Remote file requires url and mimeType.');
+            }
+            return new self($array['url'], $array['mimeType']);
+        } else {
+            if (!isset($array['mimeType']) || !isset($array['base64Data'])) {
+                throw new \InvalidArgumentException('Inline file requires mimeType and base64Data.');
+            }
+            return new self($array['base64Data'], $array['mimeType']);
+        }
+    }
 }

src/Messages/DTO/Message.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
 
 /**
@@ -14,8 +14,17 @@
  * containing a role and one or more parts with different content types.
  *
  * @since n.e.x.t
+ *
+ * @phpstan-import-type MessagePartArrayShape from MessagePart
+ *
+ * @phpstan-type MessageArrayShape array{
+ *     role: string,
+ *     parts: array<MessagePartArrayShape>
+ * }
+ *
+ * @extends AbstractDataValueObject<MessageArrayShape>
  */
-class Message implements WithJsonSchemaInterface
+class Message extends AbstractDataValueObject
 {
     /**
      * @var MessageRoleEnum The role of the message sender.
@@ -90,4 +99,47 @@ public static function getJsonSchema(): array
             'required' => ['role', 'parts'],
         ];
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     *
+     * @return MessageArrayShape
+     */
+    public function toArray(): array
+    {
+        return [
+            'role' => $this->role->value,
+            'parts' => array_map(function (MessagePart $part) {
+                return $part->toArray();
+            }, $this->parts),
+        ];
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     *
+     * @return UserMessage|ModelMessage|SystemMessage
+     */
+    final public static function fromArray(array $array): Message
+    {
+        $role = MessageRoleEnum::from($array['role']);
+        $partsData = $array['parts'];
+        $parts = array_map(function (array $partData) {
+            return MessagePart::fromArray($partData);
+        }, $partsData);
+
+        // Determine which concrete class to instantiate based on role
+        if ($role->isUser()) {
+            return new UserMessage($parts);
+        } elseif ($role->isModel()) {
+            return new ModelMessage($parts);
+        } else {
+            // System is the only remaining option
+            return new SystemMessage($parts);
+        }
+    }
 }

src/Messages/DTO/MessagePart.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Messages\Enums\MessagePartTypeEnum;
 use WordPress\AiClient\Tools\DTO\FunctionCall;
@@ -17,8 +17,22 @@
  * function calls, etc. This DTO encapsulates one such part.
  *
  * @since n.e.x.t
+ *
+ * @phpstan-import-type FileArrayShape from File
+ * @phpstan-import-type FunctionCallArrayShape from FunctionCall
+ * @phpstan-import-type FunctionResponseArrayShape from FunctionResponse
+ *
+ * @phpstan-type MessagePartArrayShape array{
+ *     type: string,
+ *     text?: string,
+ *     file?: FileArrayShape,
+ *     functionCall?: FunctionCallArrayShape,
+ *     functionResponse?: FunctionResponseArrayShape
+ * }
+ *
+ * @extends AbstractDataValueObject<MessagePartArrayShape>
  */
-class MessagePart implements WithJsonSchemaInterface
+final class MessagePart extends AbstractDataValueObject
 {
     /**
      * @var MessagePartTypeEnum The type of this message part.
@@ -202,4 +216,64 @@ public static function getJsonSchema(): array
             ],
         ];
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     *
+     * @return MessagePartArrayShape
+     */
+    public function toArray(): array
+    {
+        $data = ['type' => $this->type->value];
+
+        if ($this->type->isText() && $this->text !== null) {
+            $data['text'] = $this->text;
+        } elseif ($this->type->isFile() && $this->file !== null) {
+            $data['file'] = $this->file->toArray();
+        } elseif ($this->type->isFunctionCall() && $this->functionCall !== null) {
+            $data['functionCall'] = $this->functionCall->toArray();
+        } elseif ($this->type->isFunctionResponse() && $this->functionResponse !== null) {
+            $data['functionResponse'] = $this->functionResponse->toArray();
+        }
+
+        return $data;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    public static function fromArray(array $array): MessagePart
+    {
+        $type = MessagePartTypeEnum::from($array['type']);
+
+        if ($type->isText()) {
+            if (!isset($array['text'])) {
+                throw new \InvalidArgumentException('Text message part requires text field.');
+            }
+            return new self($array['text']);
+        } elseif ($type->isFile()) {
+            if (!isset($array['file'])) {
+                throw new \InvalidArgumentException('File message part requires file field.');
+            }
+            $fileData = $array['file'];
+            return new self(File::fromArray($fileData));
+        } elseif ($type->isFunctionCall()) {
+            if (!isset($array['functionCall'])) {
+                throw new \InvalidArgumentException('Function call message part requires functionCall field.');
+            }
+            $functionCallData = $array['functionCall'];
+            return new self(FunctionCall::fromArray($functionCallData));
+        } else {
+            // Function response is the only remaining option
+            if (!isset($array['functionResponse'])) {
+                throw new \InvalidArgumentException('Function response message part requires functionResponse field.');
+            }
+            $functionResponseData = $array['functionResponse'];
+            return new self(FunctionResponse::fromArray($functionResponseData));
+        }
+    }
 }