Use DateTimeImmutable if type is DateTimeInterface

CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `Serde` will be documented in this file.
 
 Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
 
+## Unreleased
+
+### Added
+- Nothing
+
+### Deprecated
+- Nothing
+
+### Fixed
+- A PHP type hint of `DateTimeInterface` will now deserialize to a `DateTimeImmutable` object instead of throwing an error.
+
+### Removed
+- Nothing
+
+### Security
+- Nothing
+
 ## 1.5.0 - 2025-07-15
 
 ### Added

README.md

@@ -566,6 +566,8 @@ Will serialize to this JSON:
 }
 ```
 
+Note that a type of `DateTimeInterface` will deserialize to a `DateTimeImmutable` object.
+
 #### `timezone`
 
 The `timezone` argument may be any timezone string legal in PHP, such as `America/Chicago` or `UTC`.  If specified, the value will be cast to this timezone first before it is serialized.  If not specified, the value will be left in whatever timezone it is in before being serialized.  Whether that makes a difference to the output depends on the `format`.

src/PropertyHandler/DateTimeExporter.php

@@ -68,7 +68,10 @@ public function importValue(Deserializer $deserializer, Field $field, mixed $sou
         // an opt-in/out flag to restrict the format on import should be added
         // to DateField to get used here.  Until then, this will do.
 
-        return new ($field->phpType)($string);
+        // If the PHP type is a DateTimeInterface, fulfill that with a DateTimeImmutable.
+        $type = ($field->phpType === \DateTimeInterface::class) ? \DateTimeImmutable::class : $field->phpType;
+
+        return new ($type)($string);
     }
 
     public function canImport(Field $field, string $format): bool

tests/Records/DateTimeInterfaceExample.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Crell\Serde\Records;
+
+use DateTimeInterface;
+
+class DateTimeInterfaceExample {
+    public function __construct(
+        public DateTimeInterface $interfaceProperty,
+    ) {}
+}

tests/SerdeTestCases.php

@@ -26,6 +26,7 @@
 use Crell\Serde\Records\ClassWithReducibleProperty;
 use Crell\Serde\Records\CompoundTypes;
 use Crell\Serde\Records\DateTimeExample;
+use Crell\Serde\Records\DateTimeInterfaceExample;
 use Crell\Serde\Records\DictionaryKeyTypes;
 use Crell\Serde\Records\Drupal\EmailItem;
 use Crell\Serde\Records\Drupal\FieldItemList;
@@ -339,6 +340,11 @@ public static function round_trip_examples(): iterable
                 arrayMap: ['a' => [1, 2, 3]],
             ),
         ];
+        yield 'datetimeinterface_type' => [
+            'data' => new DateTimeInterfaceExample(
+                interfaceProperty: new \DateTimeImmutable('2025-12-25 12:34:56.789'),
+            ),
+        ];
     }
 
     public static function value_object_flatten_examples(): \Generator