Update documentation and improve codebase

Author: nyamsprod

CHANGELOG.md

@@ -8,13 +8,14 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 - `Item::fromTimestamp`, `Item::fromDateFormat` to improve item instantiation with dates.
 - `ParameterAccess::parameter` to ease parameter members value access.
+- **[BC Break]**  `ParameterAccess::withoutAllParameters` is renamed `ParameterAccess::withoutAnyParameters`.
 - **[BC Break]** `OrderedList` is renamed `OuterList`.
 - **[BC Break]** `MemberContainer::remove` methods get added to the interface.
 - **[BC Break]** `MemberContainer::keys` method added to the interface.
 
 ### Fixed
 
-- Migrate to PHPUnit 10
+- Test suite migrated to PHPUnit 10
 - Improve Collection immutability with method changes
 - **[BC Break]** `ParameterAccess` interface signature updated to use the `Value` interface instead of the `Item` implementation.
 - **[BC Break]** `MemberList::remove`, `MemberOrderedMap::remove` and `MemberOrderedMap::keys` methods are moved to their parent interface.
@@ -27,7 +28,8 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Removed
 
-- **[BC Break]** `OrderedList` is remove, use `OuterList` instead.
+- **[BC Break]** `OrderedList` is removed, use `OuterList` instead.
+- **[BC Break]**  `ParameterAccess::withoutAllParameters` is removed, use `ParameterAccess::withoutAnyParameters` instead.
 - **[BC Break]**  remove the `$parameters` argument from all `Item` named constuctore except from `Item::from`.
 
 ## [0.7.0] - 2023-02-06

README.md

@@ -17,9 +17,9 @@ have them compliant with the new syntax.
 use Bakame\Http\StructuredFields\Item;
 
 $field = Item::from("/terms", ['rel' => 'copyright', 'anchor' => '#foo']);
-echo $field->toHttpValue();                // display "/terms";rel="copyright";anchor="#foo"
-echo $field->value();                      // display "/terms"
-echo $field->parameter('rel');             // display "copyright"
+echo $field->toHttpValue();     // display "/terms";rel="copyright";anchor="#foo"
+echo $field->value();           // display "/terms"
+echo $field->parameter('rel');  // display "copyright"
 ```
 
 ## System Requirements
@@ -97,7 +97,7 @@ use Bakame\Http\StructuredFields\Dictionary;
 
 $value = Dictionary::fromAssociative([
     'b' => false,
-    'a' => Item::fromToken('bar', ['baz' => 42]),
+    'a' => Item::fromToken('bar')->addParameter('baz', 42),
     'c' => new DateTimeImmutable('2022-12-23 13:00:23'),
 ]);
 

composer.json

@@ -30,11 +30,11 @@
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^v3.14.3",
         "httpwg/structured-field-tests": "*@dev",
-        "phpstan/phpstan": "^1.10.3",
+        "phpstan/phpstan": "^1.10.4",
         "phpstan/phpstan-strict-rules": "^1.5.0",
-        "phpstan/phpstan-phpunit": "^1.3.8",
+        "phpstan/phpstan-phpunit": "^1.3.10",
         "phpstan/phpstan-deprecation-rules": "^1.1.2",
-        "phpunit/phpunit": "^10.0.13"
+        "phpunit/phpunit": "^10.0.14"
     },
     "autoload": {
         "psr-4": {

src/InnerList.php

@@ -104,7 +104,7 @@ public function withoutParameter(string ...$keys): static
         return $this->withParameters($this->parameters()->remove(...$keys));
     }
 
-    public function withoutAllParameters(): static
+    public function withoutAnyParameter(): static
     {
         return $this->withParameters(Parameters::create());
     }

src/InnerListTest.php

@@ -206,7 +206,7 @@ public function it_can_create_via_parameters_access_methods_a_new_object(): void
         $instance3 = $instance1->prependParameter('a', false);
         $instance4 = $instance1->withoutParameter('b');
         $instance5 = $instance1->withoutParameter('a');
-        $instance6 = $instance1->withoutAllParameters();
+        $instance6 = $instance1->withoutAnyParameter();
 
         self::assertSame($instance1, $instance2);
         self::assertSame($instance1, $instance7);

src/Item.php

@@ -102,11 +102,11 @@ public static function fromTimestamp(int $timestamp): self
      *
      * @throws SyntaxError if the format is invalid
      */
-    public static function fromDateFormat(string $format, string $dateString): self
+    public static function fromDateFormat(string $format, string $datetime): self
     {
-        $value = DateTimeImmutable::createFromFormat($format, $dateString);
+        $value = DateTimeImmutable::createFromFormat($format, $datetime);
         if (false === $value) {
-            throw new SyntaxError('The date notation `'.$dateString.'` is incompatible with the date format `'.$format.'`.');
+            throw new SyntaxError('The date notation `'.$datetime.'` is incompatible with the date format `'.$format.'`.');
         }
 
         return self::from($value);
@@ -117,7 +117,7 @@ public static function fromDateFormat(string $format, string $dateString): self
      *
      * @throws SyntaxError if the format is invalid
      */
-    public static function fromDateString(string $dateString, DateTimeZone|string|null $timezone = null): self
+    public static function fromDateString(string $datetime, DateTimeZone|string|null $timezone = null): self
     {
         $timezone ??= date_default_timezone_get();
         if (!$timezone instanceof DateTimeZone) {
@@ -128,7 +128,13 @@ public static function fromDateString(string $dateString, DateTimeZone|string|nu
             }
         }
 
-        return self::from(new DateTimeImmutable($dateString, $timezone));
+        try {
+            $value = new DateTimeImmutable($datetime, $timezone);
+        } catch (Throwable $exception) {
+            throw new SyntaxError('Unable to create a '.DateTimeImmutable::class.' instance with the date notation `'.$datetime.'.`', 0, $exception);
+        }
+
+        return self::from($value);
     }
 
     /**
@@ -277,7 +283,7 @@ public function appendParameter(string $key, StructuredField|Token|ByteSequence|
         return $this->withParameters($this->parameters()->append($key, $member));
     }
 
-    public function withoutAllParameters(): static
+    public function withoutAnyParameter(): static
     {
         return $this->withParameters(Parameters::create());
     }

src/ItemTest.php

@@ -56,7 +56,7 @@ public function it_updates_item(mixed $value, string $expected): void
     {
         $parameters = Parameters::fromAssociative(['foo' => 'bar']);
         if ($value instanceof Value) {
-            $expected = $value->withoutAllParameters()->toHttpValue();
+            $expected = $value->withoutAnyParameter()->toHttpValue();
         }
 
         self::assertSame(
@@ -173,6 +173,22 @@ public function it_fails_to_instantiate_an_invalid_date_format_string(): void
         Item::fromDateFormat(DateTimeInterface::ATOM, '2012-02-03');
     }
 
+    #[Test]
+    public function it_fails_to_instantiate_a_date_with_an_invalid_timezone(): void
+    {
+        $this->expectException(SyntaxError::class);
+
+        Item::fromDateString('+ 5 minutes', 'foobar');
+    }
+
+    #[Test]
+    public function it_fails_to_instantiate_a_date_with_an_invalid_datetime(): void
+    {
+        $this->expectException(SyntaxError::class);
+
+        Item::fromDateString('foobar');
+    }
+
     #[Test]
     public function it_instantiates_a_binary(): void
     {
@@ -379,7 +395,7 @@ public function it_can_create_via_parameters_access_methods_a_new_object(): void
         $instance3 = $instance1->prependParameter('a', false);
         $instance4 = $instance1->withoutParameter('b');
         $instance5 = $instance1->withoutParameter('a');
-        $instance6 = $instance1->withoutAllParameters();
+        $instance6 = $instance1->withoutAnyParameter();
 
         self::assertSame($instance1, $instance2);
         self::assertSame($instance1, $instance7);

src/ParameterAccess.php

@@ -65,7 +65,7 @@ public function withoutParameter(string ...$keys): static;
      * This method MUST retain the state of the current instance, and return
      * an instance that contains the specified parameter change.
      */
-    public function withoutAllParameters(): static;
+    public function withoutAnyParameter(): static;
 
     /**
      * Returns a new instance with the newly associated parameter instance.