refactor: adds abstract DTO with json serialization

JasonTheAdams · JasonTheAdams · commit cb4406eaeed3 · 2025-07-28T15:33:57.000-06:00
diff --git a/src/Common/AbstractDataValueObject.php b/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;
+    }
+}
diff --git a/src/Files/DTO/File.php b/src/Files/DTO/File.php
@@ -4,8 +4,7 @@
 
 namespace WordPress\AiClient\Files\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\ValueObjects\MimeType;
 
@@ -24,9 +23,9 @@
  *     base64Data?: string
  * }
  *
- * @implements WithArrayTransformationInterface<FileArrayShape>
+ * @extends AbstractDataValueObject<FileArrayShape>
  */
-final class File implements WithJsonSchemaInterface, WithArrayTransformationInterface
+final class File extends AbstractDataValueObject
 {
     /**
      * @var MimeType The MIME type of the file.
diff --git a/src/Messages/DTO/Message.php b/src/Messages/DTO/Message.php
@@ -4,8 +4,7 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
 
 /**
@@ -23,9 +22,9 @@
  *     parts: array<MessagePartArrayShape>
  * }
  *
- * @implements WithArrayTransformationInterface<MessageArrayShape>
+ * @extends AbstractDataValueObject<MessageArrayShape>
  */
-class Message implements WithJsonSchemaInterface, WithArrayTransformationInterface
+class Message extends AbstractDataValueObject
 {
     /**
      * @var MessageRoleEnum The role of the message sender.
diff --git a/src/Messages/DTO/MessagePart.php b/src/Messages/DTO/MessagePart.php
@@ -4,8 +4,7 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Messages\Enums\MessagePartTypeEnum;
 use WordPress\AiClient\Tools\DTO\FunctionCall;
@@ -31,9 +30,9 @@
  *     functionResponse?: FunctionResponseArrayShape
  * }
  *
- * @implements WithArrayTransformationInterface<MessagePartArrayShape>
+ * @extends AbstractDataValueObject<MessagePartArrayShape>
  */
-final class MessagePart implements WithJsonSchemaInterface, WithArrayTransformationInterface
+final class MessagePart extends AbstractDataValueObject
 {
     /**
      * @var MessagePartTypeEnum The type of this message part.
diff --git a/src/Messages/DTO/ModelMessage.php b/src/Messages/DTO/ModelMessage.php
@@ -5,6 +5,7 @@
 namespace WordPress\AiClient\Messages\DTO;
 
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
+use WordPress\AiClient\Common\Traits\HasJsonSerialization;
 
 /**
  * Represents a message from the AI model.
diff --git a/src/Messages/DTO/SystemMessage.php b/src/Messages/DTO/SystemMessage.php
@@ -5,6 +5,7 @@
 namespace WordPress\AiClient\Messages\DTO;
 
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
+use WordPress\AiClient\Common\Traits\HasJsonSerialization;
 
 /**
  * Represents a system instruction message.
diff --git a/src/Messages/DTO/UserMessage.php b/src/Messages/DTO/UserMessage.php
@@ -5,6 +5,7 @@
 namespace WordPress\AiClient\Messages\DTO;
 
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
+use WordPress\AiClient\Common\Traits\HasJsonSerialization;
 
 /**
  * Represents a message from a user.
diff --git a/src/Operations/Contracts/OperationInterface.php b/src/Operations/Contracts/OperationInterface.php
@@ -4,8 +4,6 @@
 
 namespace WordPress\AiClient\Operations\Contracts;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
 use WordPress\AiClient\Operations\Enums\OperationStateEnum;
 
 /**
@@ -15,12 +13,8 @@
  * They provide a way to track the progress and retrieve results asynchronously.
  *
  * @since n.e.x.t
- *
- * @template TArrayShape of array<string, mixed>
- *
- * @extends WithArrayTransformationInterface<TArrayShape>
  */
-interface OperationInterface extends WithJsonSchemaInterface, WithArrayTransformationInterface
+interface OperationInterface
 {
     /**
      * Gets the operation ID.
diff --git a/src/Operations/DTO/GenerativeAiOperation.php b/src/Operations/DTO/GenerativeAiOperation.php
@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Operations\DTO;
 
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Operations\Contracts\OperationInterface;
 use WordPress\AiClient\Operations\Enums\OperationStateEnum;
 use WordPress\AiClient\Results\DTO\GenerativeAiResult;
@@ -20,9 +21,9 @@
  *
  * @phpstan-type GenerativeAiOperationArrayShape array{id: string, state: string, result?: GenerativeAiResultArrayShape}
  *
- * @implements OperationInterface<GenerativeAiOperationArrayShape>
+ * @extends AbstractDataValueObject<GenerativeAiOperationArrayShape>
  */
-final class GenerativeAiOperation implements OperationInterface
+final class GenerativeAiOperation extends AbstractDataValueObject implements OperationInterface
 {
     /**
      * @var string Unique identifier for this operation.
diff --git a/src/Results/Contracts/ResultInterface.php b/src/Results/Contracts/ResultInterface.php
@@ -4,8 +4,6 @@
 
 namespace WordPress\AiClient\Results\Contracts;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
 use WordPress\AiClient\Results\DTO\TokenUsage;
 
 /**
@@ -15,12 +13,8 @@
  * such as token usage and provider-specific information.
  *
  * @since n.e.x.t
- *
- * @template TArrayShape of array<string, mixed>
- *
- * @extends WithArrayTransformationInterface<TArrayShape>
  */
-interface ResultInterface extends WithJsonSchemaInterface, WithArrayTransformationInterface
+interface ResultInterface
 {
     /**
      * Gets the result ID.
diff --git a/src/Results/DTO/Candidate.php b/src/Results/DTO/Candidate.php
@@ -4,8 +4,7 @@
 
 namespace WordPress\AiClient\Results\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Messages\DTO\Message;
 use WordPress\AiClient\Results\Enums\FinishReasonEnum;
 
@@ -21,9 +20,9 @@
  *
  * @phpstan-type CandidateArrayShape array{message: MessageArrayShape, finishReason: string, tokenCount: int|string}
  *
- * @implements WithArrayTransformationInterface<CandidateArrayShape>
+ * @extends AbstractDataValueObject<CandidateArrayShape>
  */
-final class Candidate implements WithJsonSchemaInterface, WithArrayTransformationInterface
+final class Candidate extends AbstractDataValueObject
 {
     /**
      * @var Message The generated message.
diff --git a/src/Results/DTO/GenerativeAiResult.php b/src/Results/DTO/GenerativeAiResult.php
@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Results\DTO;
 
+use WordPress\AiClient\Common\AbstractDataValueObject;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Messages\DTO\Message;
 use WordPress\AiClient\Messages\Enums\MessagePartTypeEnum;
@@ -27,9 +28,9 @@
  *     providerMetadata?: array<string, mixed>
  * }
  *
- * @implements ResultInterface<GenerativeAiResultArrayShape>
+ * @extends AbstractDataValueObject<GenerativeAiResultArrayShape>
  */
-final class GenerativeAiResult implements ResultInterface
+final class GenerativeAiResult extends AbstractDataValueObject implements ResultInterface
 {
     /**
      * @var string Unique identifier for this result.
diff --git a/src/Results/DTO/TokenUsage.php b/src/Results/DTO/TokenUsage.php
@@ -4,8 +4,7 @@
 
 namespace WordPress\AiClient\Results\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 
 /**
  * Represents token usage statistics for an AI operation.
@@ -21,9 +20,9 @@
  *     totalTokens: int|string
  * }
  *
- * @implements WithArrayTransformationInterface<TokenUsageArrayShape>
+ * @extends AbstractDataValueObject<TokenUsageArrayShape>
  */
-final class TokenUsage implements WithJsonSchemaInterface, WithArrayTransformationInterface
+final class TokenUsage extends AbstractDataValueObject
 {
     /**
      * @var int Number of tokens in the prompt.
diff --git a/src/Tools/DTO/FunctionCall.php b/src/Tools/DTO/FunctionCall.php
@@ -4,8 +4,7 @@
 
 namespace WordPress\AiClient\Tools\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 
 /**
  * Represents a function call request from an AI model.
@@ -17,9 +16,9 @@
  *
  * @phpstan-type FunctionCallArrayShape array{id?: string, name?: string, args?: mixed}
  *
- * @implements WithArrayTransformationInterface<FunctionCallArrayShape>
+ * @extends AbstractDataValueObject<FunctionCallArrayShape>
  */
-final class FunctionCall implements WithJsonSchemaInterface, WithArrayTransformationInterface
+final class FunctionCall extends AbstractDataValueObject
 {
     /**
      * @var string|null Unique identifier for this function call.
diff --git a/src/Tools/DTO/FunctionDeclaration.php b/src/Tools/DTO/FunctionDeclaration.php
@@ -4,8 +4,7 @@
 
 namespace WordPress\AiClient\Tools\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 
 /**
  * Represents a function declaration for AI models.
@@ -17,9 +16,9 @@
  *
  * @phpstan-type FunctionDeclarationArrayShape array{name: string, description: string, parameters?: mixed}
  *
- * @implements WithArrayTransformationInterface<FunctionDeclarationArrayShape>
+ * @extends AbstractDataValueObject<FunctionDeclarationArrayShape>
  */
-final class FunctionDeclaration implements WithJsonSchemaInterface, WithArrayTransformationInterface
+final class FunctionDeclaration extends AbstractDataValueObject
 {
     /**
      * @var string The name of the function.
diff --git a/src/Tools/DTO/FunctionResponse.php b/src/Tools/DTO/FunctionResponse.php
@@ -4,8 +4,7 @@
 
 namespace WordPress\AiClient\Tools\DTO;
 
-use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
-use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
+use WordPress\AiClient\Common\AbstractDataValueObject;
 
 /**
  * Represents a response to a function call.
@@ -17,9 +16,9 @@
  *
  * @phpstan-type FunctionResponseArrayShape array{id: string, name: string, response: mixed}
  *
- * @implements WithArrayTransformationInterface<FunctionResponseArrayShape>
+ * @extends AbstractDataValueObject<FunctionResponseArrayShape>
  */
-final class FunctionResponse implements WithJsonSchemaInterface, WithArrayTransformationInterface
+final class FunctionResponse extends AbstractDataValueObject
 {
     /**
      * @var string The ID of the function call this is responding to.
diff --git a/src/Tools/DTO/Tool.php b/src/Tools/DTO/Tool.php
diff --git a/src/Tools/DTO/WebSearch.php b/src/Tools/DTO/WebSearch.php
diff --git a/tests/unit/Common/AbstractDataValueObjectTest.php b/tests/unit/Common/AbstractDataValueObjectTest.php

Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@`
`4`	`4`
`5`	`5`	`namespace WordPress\AiClient\Operations\DTO;`
`6`	`6`
	`7`	`+use WordPress\AiClient\Common\AbstractDataValueObject;`
`7`	`8`	`use WordPress\AiClient\Operations\Contracts\OperationInterface;`
`8`	`9`	`use WordPress\AiClient\Operations\Enums\OperationStateEnum;`
`9`	`10`	`use WordPress\AiClient\Results\DTO\GenerativeAiResult;`
`@@ -20,9 +21,9 @@`
`20`	`21`	`*`
`21`	`22`	`* @phpstan-type GenerativeAiOperationArrayShape array{id: string, state: string, result?: GenerativeAiResultArrayShape}`
`22`	`23`	`*`
`23`		`- * @implements OperationInterface<GenerativeAiOperationArrayShape>`
	`24`	`+ * @extends AbstractDataValueObject<GenerativeAiOperationArrayShape>`
`24`	`25`	`*/`
`25`		`-final class GenerativeAiOperation implements OperationInterface`
	`26`	`+final class GenerativeAiOperation extends AbstractDataValueObject implements OperationInterface`
`26`	`27`	`{`
`27`	`28`	`/**`
`28`	`29`	`* @var string Unique identifier for this operation.`