Simplify public API

Author: nyamsprod

CHANGELOG.md

@@ -28,6 +28,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 ### Removed
 
 - **[BC Break]** `OrderedList` is remove, use `OuterList` instead.
+- **[BC Break]**  remove the `$parameters` argument from all `Item` named constuctore except from `Item::from`.
 
 ## [0.7.0] - 2023-02-06
 

README.md

@@ -272,11 +272,14 @@ use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Value;
 
 Item::from($value, iterable<string, Value> $associativeParameters = []): self;
-Item::fromDecodedByteSequence(string $value, iterable<string, Value> $associativeParameters = []): self;
-Item::fromEncodedByteSequence(string $value, iterable<string, Value> $associativeParameters = []): self;
-Item::fromTimestamp(int $value, iterable<string, Value> $associativeParameters = []): self;
-Item::fromDateFormat(string $dateFormat, string $dateString, iterable<string, Value> $associativeParameters = []): self;
-Item::fromPair(array{0:mixed, 1:iterable<array{0:string, 1:StructuredField}>} $pair): self;
+Item::fromPair(array{0:mixed, 1:iterable<array{0:string, 1:Value}>} $pair): self;
+Item::fromDecodedByteSequence(string $value): self;
+Item::fromEncodedByteSequence(string $value): self;
+Item::fromToken(string $value): self;
+Item::fromDate(DateTimeInterface $value): self;
+Item::fromTimestamp(int $value): self;
+Item::fromDateFormat(string $dateFormat, string $dateString): self;
+Item::fromDateFormat(string $dateString, DateTimeZone|string|null $timezone): self;
 ```
 
 ### Accessing members of Structured Fields Containers.

src/Item.php

@@ -6,7 +6,9 @@
 
 use DateTimeImmutable;
 use DateTimeInterface;
+use DateTimeZone;
 use Stringable;
+use Throwable;
 use function count;
 use function is_bool;
 use function is_float;
@@ -65,59 +67,68 @@ public static function fromHttpValue(Stringable|string $httpValue): self
 
     /**
      * Returns a new instance from an encoded byte sequence and an iterable of key-value parameters.
-     *
-     * @param iterable<string,Value|DataType> $parameters
      */
-    public static function fromEncodedByteSequence(Stringable|string $value, iterable $parameters = []): self
+    public static function fromEncodedByteSequence(Stringable|string $value): self
     {
-        return self::from(ByteSequence::fromEncoded($value), $parameters);
+        return self::from(ByteSequence::fromEncoded($value));
     }
 
     /**
      * Returns a new instance from a decoded byte sequence and an iterable of key-value parameters.
-     *
-     * @param iterable<string,Value|DataType> $parameters
      */
-    public static function fromDecodedByteSequence(Stringable|string $value, iterable $parameters = []): self
+    public static function fromDecodedByteSequence(Stringable|string $value): self
     {
-        return self::from(ByteSequence::fromDecoded($value), $parameters);
+        return self::from(ByteSequence::fromDecoded($value));
     }
 
     /**
      * Returns a new instance from a Token and an iterable of key-value parameters.
-     *
-     * @param iterable<string,Value|DataType> $parameters
      */
-    public static function fromToken(Stringable|string $value, iterable $parameters = []): self
+    public static function fromToken(Stringable|string $value): self
     {
-        return self::from(Token::fromString($value), $parameters);
+        return self::from(Token::fromString($value));
     }
 
     /**
      * 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
+    public static function fromTimestamp(int $timestamp): self
     {
-        return self::from((new DateTimeImmutable())->setTimestamp($timestamp), $parameters);
+        return self::from((new DateTimeImmutable())->setTimestamp($timestamp));
     }
 
     /**
      * 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
+     * @throws SyntaxError if the format is invalid
      */
-    public static function fromDateFormat(string $format, string $dateString, iterable $parameters = []): self
+    public static function fromDateFormat(string $format, string $dateString): self
     {
-        $date = DateTimeImmutable::createFromFormat($format, $dateString);
-        if (false === $date) {
+        $value = DateTimeImmutable::createFromFormat($format, $dateString);
+        if (false === $value) {
             throw new SyntaxError('The date notation `'.$dateString.'` is incompatible with the date format `'.$format.'`.');
         }
 
-        return self::from($date, $parameters);
+        return self::from($value);
+    }
+
+    /**
+     * Returns a new instance from a string parsable by DateTimeImmutable constructor, an optional timezone and an iterable of key-value parameters.
+     *
+     * @throws SyntaxError if the format is invalid
+     */
+    public static function fromDateString(string $dateString, DateTimeZone|string|null $timezone = null): self
+    {
+        $timezone ??= date_default_timezone_get();
+        if (!$timezone instanceof DateTimeZone) {
+            try {
+                $timezone = new DateTimeZone($timezone);
+            } catch (Throwable $exception) {
+                throw new SyntaxError('The timezone could not be instantiated.', 0, $exception);
+            }
+        }
+
+        return self::from(new DateTimeImmutable($dateString, $timezone));
     }
 
     /**

src/ItemTest.php

@@ -121,6 +121,7 @@ public function it_instantiates_a_date(): void
         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::assertTrue($item ->value() < Item::fromDateString('-1 year')->value());
         self::assertSame('@1583349795', $item->toHttpValue());
     }