Adds DTO array transformation and JSON serialization

src/Common/AbstractDataValueObject.php

@@ -0,0 +1,131 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Common;
+
+use InvalidArgumentException;
+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
+{
+    /**
+     * 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 (!array_key_exists($key, $data)) {
+                $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.
+     *
+     * 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 n.e.x.t
+ *
+ * @template TArrayShape of array<string, mixed>
+ */
+interface WithArrayTransformationInterface
+{
+    /**
+     * Converts the object to an array representation.
+     *
+     * @since n.e.x.t
+     *
+     * @return TArrayShape The array representation.
+     */
+    public function toArray(): array;
+
+    /**
+     * Creates an instance from array data.
+     *
+     * @since n.e.x.t
+     *
+     * @param TArrayShape $array The array data.
+     * @return self<TArrayShape> The created instance.
+     */
+    public static function fromArray(array $array): self;
+}

src/Files/DTO/File.php

@@ -4,7 +4,9 @@
 
 namespace WordPress\AiClient\Files\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
+use InvalidArgumentException;
+use RuntimeException;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\ValueObjects\MimeType;
 
@@ -15,9 +17,22 @@
  * 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
+class File extends AbstractDataValueObject
 {
+    public const KEY_FILE_TYPE = 'fileType';
+    public const KEY_MIME_TYPE = 'mimeType';
+    public const KEY_URL = 'url';
+    public const KEY_BASE64_DATA = 'base64Data';
     /**
      * @var MimeType The MIME type of the file.
      */
@@ -335,46 +350,94 @@ public static function getJsonSchema(): array
             'oneOf' => [
                 [
                     'properties' => [
-                        'fileType' => [
+                        self::KEY_FILE_TYPE => [
                             'type' => 'string',
                             'const' => FileTypeEnum::REMOTE,
                             'description' => 'The file type.',
                         ],
-                        'mimeType' => [
+                        self::KEY_MIME_TYPE => [
                             'type' => 'string',
                             'description' => 'The MIME type of the file.',
                             'pattern' => '^[a-zA-Z0-9][a-zA-Z0-9!#$&\\-\\^_+.]*\\/[a-zA-Z0-9]'
                                 . '[a-zA-Z0-9!#$&\\-\\^_+.]*$',
                         ],
-                        'url' => [
+                        self::KEY_URL => [
                             'type' => 'string',
                             'format' => 'uri',
                             'description' => 'The URL to the remote file.',
                         ],
                     ],
-                    'required' => ['fileType', 'mimeType', 'url'],
+                    'required' => [self::KEY_FILE_TYPE, self::KEY_MIME_TYPE, self::KEY_URL],
                 ],
                 [
                     'properties' => [
-                        'fileType' => [
+                        self::KEY_FILE_TYPE => [
                             'type' => 'string',
                             'const' => FileTypeEnum::INLINE,
                             'description' => 'The file type.',
                         ],
-                        'mimeType' => [
+                        self::KEY_MIME_TYPE => [
                             'type' => 'string',
                             'description' => 'The MIME type of the file.',
                             'pattern' => '^[a-zA-Z0-9][a-zA-Z0-9!#$&\\-\\^_+.]*\\/[a-zA-Z0-9]'
                                 . '[a-zA-Z0-9!#$&\\-\\^_+.]*$',
                         ],
-                        'base64Data' => [
+                        self::KEY_BASE64_DATA => [
                             'type' => 'string',
                             'description' => 'The base64-encoded file data.',
                         ],
                     ],
-                    'required' => ['fileType', 'mimeType', 'base64Data'],
+                    'required' => [self::KEY_FILE_TYPE, self::KEY_MIME_TYPE, self::KEY_BASE64_DATA],
                 ],
             ],
         ];
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     *
+     * @return FileArrayShape
+     */
+    public function toArray(): array
+    {
+        $data = [
+            self::KEY_FILE_TYPE => $this->fileType->value,
+            self::KEY_MIME_TYPE => $this->getMimeType(),
+        ];
+
+        if ($this->url !== null) {
+            $data[self::KEY_URL] = $this->url;
+        } elseif (!$this->fileType->isRemote() && $this->base64Data !== null) {
+            $data[self::KEY_BASE64_DATA] = $this->base64Data;
+        } else {
+            throw new RuntimeException(
+                'File requires either url or base64Data. This should not be a possible condition.'
+            );
+        }
+
+        return $data;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    public static function fromArray(array $array): self
+    {
+        static::validateFromArrayData($array, [self::KEY_FILE_TYPE]);
+
+        // Check which properties are set to determine how to construct the File
+        $mimeType = $array[self::KEY_MIME_TYPE] ?? null;
+
+        if (isset($array[self::KEY_URL])) {
+            return new self($array[self::KEY_URL], $mimeType);
+        } elseif (isset($array[self::KEY_BASE64_DATA])) {
+            return new self($array[self::KEY_BASE64_DATA], $mimeType);
+        } else {
+            throw new InvalidArgumentException('File requires either url or base64Data.');
+        }
+    }
 }