Adding Date related named constructors

Author: nyamsprod

CHANGELOG.md

@@ -6,6 +6,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Added
 
+- `Item::fromTimestamp`, `Item::fromDateFormat` to improve item instantiation with dates.
 - `ParameterAccess::parameter` to ease parameter members value access.
 - **[BC Break]** `OrderedList` is renamed `OuterList`.
 - **[BC Break]** `MemberContainer::remove` methods get added to the interface.

src/InnerList.php

@@ -115,7 +115,7 @@ public function withParameters(Parameters $parameters): static
             return $this;
         }
 
-        return new self($parameters, $this->members);
+        return new static($parameters, $this->members);
     }
 
     public function toHttpValue(): string

src/Item.php

@@ -93,6 +93,33 @@ public static function fromToken(Stringable|string $value, iterable $parameters
         return self::from(Token::fromString($value), $parameters);
     }
 
+    /**
+     * Returns a new instance from a timestamp and an iterable of key-value parameters.
+     *
+     * @param iterable<string,Value|DataType> $parameters
+     */
+    public static function fromTimestamp(int $timestamp, iterable $parameters = []): self
+    {
+        return self::from((new DateTimeImmutable())->setTimestamp($timestamp), $parameters);
+    }
+
+    /**
+     * Returns a new instance from a date format its date string representation and an iterable of key-value parameters.
+     *
+     * @param iterable<string,Value|DataType> $parameters
+     *
+     * @throws SyntaxError if the fornat is
+     */
+    public static function fromDateFormat(string $format, string $dateString, iterable $parameters = []): self
+    {
+        $date = DateTimeImmutable::createFromFormat($format, $dateString);
+        if (false === $date) {
+            throw new SyntaxError('The date notation `'.$dateString.'` is incompatible with the date format `'.$format.'`.');
+        }
+
+        return self::from($date, $parameters);
+    }
+
     /**
      * @param array{
      *     0:DataType,
@@ -251,7 +278,7 @@ public function withoutParameter(string ...$keys): static
 
     public function withParameters(Parameters $parameters): static
     {
-        return $this->parameters->toHttpValue() === $parameters->toHttpValue() ? $this : new self($this->value, $parameters);
+        return $this->parameters->toHttpValue() === $parameters->toHttpValue() ? $this : new static($this->value, $parameters);
     }
 
     /**

src/ItemTest.php

@@ -7,6 +7,7 @@
 use ArrayObject;
 use DateTime;
 use DateTimeImmutable;
+use DateTimeInterface;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Test;
 use Stringable;
@@ -60,7 +61,7 @@ public function it_updates_item(mixed $value, string $expected): void
 
         self::assertSame(
             $expected.$parameters->toHttpValue(),
-            Item::from('hello-world', $parameters)->withValue($value)->toHttpValue()
+            (string) Item::from('hello-world', $parameters)->withValue($value)
         );
     }
 
@@ -118,6 +119,8 @@ public function it_instantiates_a_date(): void
         $item = Item::fromHttpValue('@1583349795');
         self::assertEquals($item, Item::from(new DateTimeImmutable('2020-03-04 19:23:15')));
         self::assertEquals($item, Item::from(new DateTime('2020-03-04 19:23:15')));
+        self::assertEquals($item, Item::fromTimestamp(1583349795));
+        self::assertEquals($item, Item::fromDateFormat(DateTimeInterface::RFC822, 'Wed, 04 Mar 20 19:23:15 +0000'));
         self::assertSame('@1583349795', $item->toHttpValue());
     }
 
@@ -137,6 +140,14 @@ public function it_fails_to_instantiate_an_out_of_range_date_in_the_future(): vo
         Item::from(new DateTime('@'. 1_000_000_000_000_000));
     }
 
+    #[Test]
+    public function it_fails_to_instantiate_an_out_of_range_timestamp_in_the_future(): void
+    {
+        $this->expectException(SyntaxError::class);
+
+        Item::fromTimestamp(1_000_000_000_000_000);
+    }
+
     #[Test]
     public function it_fails_to_instantiate_an_out_of_range_date_in_the_past(): void
     {
@@ -145,6 +156,22 @@ public function it_fails_to_instantiate_an_out_of_range_date_in_the_past(): void
         Item::from(new DateTime('@'.-1_000_000_000_000_000));
     }
 
+    #[Test]
+    public function it_fails_to_instantiate_an_out_of_range_timestamp_in_the_past(): void
+    {
+        $this->expectException(SyntaxError::class);
+
+        Item::fromTimestamp(-1_000_000_000_000_000);
+    }
+
+    #[Test]
+    public function it_fails_to_instantiate_an_invalid_date_format_string(): void
+    {
+        $this->expectException(SyntaxError::class);
+
+        Item::fromDateFormat(DateTimeInterface::ATOM, '2012-02-03');
+    }
+
     #[Test]
     public function it_instantiates_a_binary(): void
     {