Merge pull request #54 from gapple/datetimeinterface

Allow serializing any \DateTimeInterface object as an Item value

Author: gapple

.editorconfig

@@ -11,6 +11,7 @@ indent_style = space
 indent_size = 4
 
 [*.md]
+indent_size = 2
 trim_trailing_whitespace = false
 
 [*.yml]

readme.md

@@ -39,4 +39,34 @@ Serializer::serializeList(iterable): string;
 Serializer::serializeDictionary(object): string;
 ```
 
+### Special Types
+`Serializer` will accept `string` or any `Stringable` object as an Item value, 
+but will throw a `SerializeException` if it contains any characters outside the
+printable ASCII range.
+
+Special Item types must use a decorating class in order to be serialized correctly:
+
+- **Byte Sequences** (`\gapple\StructuredFields\Bytes`)  
+  A string containing binary data.  
+
+  `Serializer` and `Parser` handle base64 encoding and decoding the provided string.
+
+
+- **Display Strings** (`\gapple\StructuredFields\DisplayString`)  
+  A string that includes Unicode characters.
+
+  `Serializer` and `Parser` handle percent-encoding and decoding non-ascii characters.
+
+
+- **Tokens** (`\gapple\StructuredFields\Token`)  
+  A short textual word with a restricted character set.
+ 
+
+- **Dates** (`\gapple\StructuredFields\Date`)  
+  An integer timestamp
+
+  `Serializer` accepts any object that implements `\DateTimeInterface`.   
+  `Parser` will return a `\gapple\StructuredFields\Date` object.
+
+  
 [1]: https://www.rfc-editor.org/rfc/rfc9651.html

src/Date.php

@@ -4,14 +4,19 @@
 
 namespace gapple\StructuredFields;
 
-class Date
+class Date extends \DateTimeImmutable
 {
-    public function __construct(private readonly int $value)
+    public function __construct(int $timestamp)
     {
+        parent::__construct("@{$timestamp}");
     }
 
+    /**
+     * @deprecated in 2.3.0 and will be removed from 3.0.0.  Use Date::getTimestamp() instead.
+     * @codeCoverageIgnore
+     */
     public function toInt(): int
     {
-        return $this->value;
+        return $this->getTimestamp();
     }
 }

src/Serializer.php

@@ -153,14 +153,14 @@ private static function serializeBareItem(mixed $value): string
             return self::serializeDecimal($value);
         } elseif (is_bool($value)) {
             return self::serializeBoolean($value);
-        } elseif ($value instanceof Token) {
-            return self::serializeToken($value);
+        } elseif ($value instanceof \DateTimeInterface) {
+            return self::serializeDate($value);
         } elseif ($value instanceof Bytes) {
             return self::serializeByteSequence($value);
-        } elseif ($value instanceof Date) {
-            return self::serializeDate($value);
         } elseif ($value instanceof DisplayString) {
             return self::serializeDisplayString($value);
+        } elseif ($value instanceof Token) {
+            return self::serializeToken($value);
         } elseif (is_string($value) || $value instanceof \Stringable) {
             return self::serializeString((string) $value);
         }
@@ -260,9 +260,9 @@ private static function serializeParameters(object $value): string
         return $returnValue;
     }
 
-    private static function serializeDate(Date $value): string
+    private static function serializeDate(\DateTimeInterface $value): string
     {
-        return '@' . self::serializeInteger($value->toInt());
+        return '@' . self::serializeInteger($value->getTimestamp());
     }
 
     private static function serializeKey(string $value): string

tests/DateTest.php

@@ -2,35 +2,47 @@
 
 namespace gapple\Tests\StructuredFields;
 
+use gapple\StructuredFields\Item;
+
 /**
  * Additional Date parsing and serializing tests.
  */
 class DateTest extends RulesetTestBase
 {
     use ParsingRulesetTrait;
+    use SerializingRulesetTrait;
 
     /**
      * {@inheritdoc}
      */
     protected static function rulesetDataProvider(): array
     {
         return [
-            'date - large int' => [
+            'large int' => [
                 Rule::fromArray([
                     'name' => 'date - large int',
                     'raw' => ['@1234567890123456'],
                     'header_type' => 'item',
                     'must_fail' => true,
                 ]),
             ],
-            'date - hexadecimal' => [
+            'hexadecimal' => [
                 Rule::fromArray([
                     'name' => 'date - hexadecimal',
                     'raw' => ['@0x62EB2779'],
                     'header_type' => 'item',
                     'must_fail' => true,
                 ]),
             ],
+            // Serialize any \DateTimeInterface object.
+            'DateTimeInterface' => [
+              Rule::fromArray([
+                  'name' => 'date - DateTimeInterface',
+                  'header_type' => 'item',
+                  'expected' => new Item(new \DateTimeImmutable('@629528400')),
+                  'canonical' => ['@629528400'],
+              ]),
+            ],
         ];
     }
 }

tests/Httpwg/HttpwgRuleExpectedConverter.php

@@ -122,9 +122,9 @@ private static function innerList(array $innerList): InnerList
      *
      * @param ExpectedBareValue $data
      *   The expected bare value.
-     * @return bool|int|float|string|Bytes|Date|DisplayString|Token
+     * @return bool|int|float|string|Bytes|\DateTimeInterface|DisplayString|Token
      */
-    private static function value($data)
+    private static function value($data): mixed
     {
         if (!is_object($data)) {
             return $data;