Date value serialization

Author: n.gnato

CHANGELOG.md

@@ -6,9 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Built-in DateTime and DateTimeInterface fields value wrapper for json serialization according to jsonapi spec Examples.
+
 ## [0.0.8] - 2025-08-25
 
-## Added
+### Added
 - BaseKeyValueStructure::assignFieldValue() method for inject custom field instantiation logic. 
 - DateTimeInterface support for as field types. 
 

src/FreeElephants/JsonApi/DTO/BaseKeyValueStructure.php

@@ -2,6 +2,8 @@
 
 namespace FreeElephants\JsonApi\DTO;
 
+use FreeElephants\JsonApi\DTO\Field\DateTimeFieldValue;
+
 class BaseKeyValueStructure
 {
     public function __construct(array $attributes)
@@ -22,8 +24,8 @@ protected function assignFieldValue(string $name, $value): self
                     $value = null;
                 } else {
                     $propertyClassName = $propertyType->getName();
-                    if($propertyClassName === \DateTimeInterface::class) {
-                        $value = new \DateTime($value);
+                    if(in_array($propertyClassName, [\DateTimeInterface::class, \DateTime::class])) {
+                        $value = new DateTimeFieldValue($value);
                     } else {
                         $value = new $propertyClassName($value);
                     }

src/FreeElephants/JsonApi/DTO/Field/DateTimeFieldValue.php

@@ -0,0 +1,20 @@
+<?php
+declare(strict_types=1);
+
+namespace FreeElephants\JsonApi\DTO\Field;
+
+class DateTimeFieldValue extends \DateTime implements \JsonSerializable
+{
+    public const DEFAULT_JSONAPI_DATE_FORMAT = 'Y-m-d\TH:i:s.vp';
+    private static string $format = self::DEFAULT_JSONAPI_DATE_FORMAT;
+
+    public static function setFormat(string $format)
+    {
+        self::$format = $format;
+    }
+
+    public function jsonSerialize(): string
+    {
+        return $this->format(self::$format);
+    }
+}

tests/FreeElephants/JsonApi/DTO/DocumentTest.php

@@ -11,7 +11,7 @@ class DocumentTest extends AbstractTestCase
     public function testFromRequest()
     {
         $request = new ServerRequest('POST', '/foo');
-        $request->getBody()->write(<<<JSON
+        $rawJson = <<<JSON
 {
     "data": {
         "id": "123",
@@ -38,7 +38,8 @@ public function testFromRequest()
         }
     }
 }
-JSON
+JSON;
+        $request->getBody()->write($rawJson
         );
 
         $fooDTO = FooDocument::fromHttpMessage($request);
@@ -53,6 +54,8 @@ public function testFromRequest()
         $this->assertNull($fooDTO->data->attributes->nullableObjectField);
         $this->assertNull($fooDTO->data->attributes->nullableScalarField);
         $this->assertSame('baz', $fooDTO->data->attributes->nullableScalarFilledField);
+
+        $this->assertJsonStringEqualsJsonString($rawJson, json_encode($fooDTO));
     }
 }