Normalize building and updating parameters for Item and InnerList

Author: nyamsprod

CHANGELOG.md

@@ -12,6 +12,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - `Item` implements the `ValueAccess` interface;
 - `Item::toPair` to complement `Item::fromPair`;
 - `Item::fromDate` to improve and complete the Item Date public API;
+- `Item::fromAssociative` to improve Item public API;
 - `Value` internal class to improve Item public API;
 - `Token::toString` to return the string representation of the token.
 
@@ -29,6 +30,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - **[BC Break]** `InnerList::fromAssociativeParameters` use `InnerList::fromAssociative` instead.
 - **[BC Break]** `Value` interface use a combination of `ValueAccess` **and** `ParameterAccess` instead.
 - **[BC Break]** `Token::value` is no longer public use `Token::toString` instead.
+- **[BC Break]** `Item::from` is removed use `Item::fromAssociative` instead.
 
 ## [0.8.0] - 2023-03-12
 

README.md

@@ -149,7 +149,7 @@ use Bakame\Http\StructuredFields\Type;
 
 //@type SfItemInput ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|bool
 // the Item::value() can return one of those type
-$item = Item::from(CarbonImmutable::parse('today'));
+$item = Item::fromDate(CarbonImmutable::parse('today'));
 $item->type();  // return Type::Date;
 $item->value()  // return a CarbonImmutable instance because it extends DateTimeImmutable
 // you can also do 
@@ -200,10 +200,12 @@ using the following methods:
 ```php
 use Bakame\Http\StructuredFields\Parameters;
 
-$innerList->parameter($key): ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|bool|null;
-$innerList->parameters(): Parameters;
+$field->parameter(string $key): ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|bool|null;
+$field->parameters(): Parameters;
 ```
 
+**Of note: the `parameter` method will return `null` if no value is found for the given index.**
+
 ### Building and Updating Structured Fields Values
 
 Every value object can be used as a builder to create an HTTP field value.
@@ -246,12 +248,12 @@ use Bakame\Http\StructuredFields\Dictionary;
 
 $value = Dictionary::fromAssociative([
     'b' => false,
-    'a' => Item::fromToken('bar')->addParameter('baz', 42),
+    'a' => Item::fromToken('bar'),
     'c' => new DateTimeImmutable('2022-12-23 13:00:23'),
 ]);
 
-echo $value->toHttpValue(); //"b=?0, a=bar;baz=42, c=@1671800423"
-echo $value;                //"b=?0, a=bar;baz=42, c=@1671800423"
+echo $value->toHttpValue(); //"b=?0, a=bar, c=@1671800423"
+echo $value;                //"b=?0, a=bar, c=@1671800423"
 ```
 
 Or with an iterable structure of pairs as per defined in the RFC:
@@ -269,23 +271,23 @@ echo $value->toHttpValue(); //;b=?0;a=bar;c=@1671800423
 echo $value;                //;b=?0;a=bar;c=@1671800423
 ```
 
-If the preference is to use the builder pattern, the same result can be achieved with the following steps:
+If the preference is to use the builder pattern, the same result can be achieved with the following steps.
+We start building a `Parameters` or a `Dictionary` instance using the `create` named constructor which
+returns a new instance with no members.
 
 ```php
 use Bakame\Http\StructuredFields\Dictionary;
 use Bakame\Http\StructuredFields\Item;
 use Bakame\Http\StructuredFields\Token;
 
-$bar = Item::fromToken('bar')
-    ->addParameter('baz', Item::from(42));
 $value = Dictionary::create()
-    ->add('a', $bar)
-    ->prepend('b', Item::from(false))
-    ->append('c', Item::from(new DateTimeImmutable('2022-12-23 13:00:23')))
+    ->add('a', Item::fromToken('bar'))
+    ->prepend('b', Item::false())
+    ->append('c', Item::fromDateString('2022-12-23 13:00:23'))
 ;
 
-echo $value->toHttpValue(); //"b=?0, a=bar;baz=42, c=@1671800423"
-echo $value;                //"b=?0, a=bar;baz=42, c=@1671800423"
+echo $value->toHttpValue(); //"b=?0, a=bar, c=@1671800423"
+echo $value;                //"b=?0, a=bar, c=@1671800423"
 ```
 
 Because we are using immutable value objects any change to the value object will return a new instance with
@@ -304,7 +306,7 @@ $map->remove(...$key): static;
 
 #### Lists
 
-To Create `OuterList` and `InnerList` instances you can use the `from` name constructor:
+To Create `OuterList` and `InnerList` instances you can use the `from` named constructor:
 
 ```php
 use Bakame\Http\StructuredFields\InnerList;
@@ -341,27 +343,28 @@ echo $list;                //'(:SGVsbG8gV29ybGQ=: 42.0 42)'
 ```php
 $list->unshift(...$members): static;
 $list->push(...$members): static;
-$list->insert($key, ...$members): static;
-$list->replace($key, $member): static;
-$list->remove(...$key): static;
+$list->insert(int $key, ...$members): static;
+$list->replace(int $key, $member): static;
+$list->remove(int ...$key): static;
 ```
 
 #### Adding and updating parameters
 
-It is also possible to instantiate an `InnerList` or an `Item` instance with included parameters
-using one of these named constructors:
+To ease working with instance that have a `Parameters` object attached to the following
+public API is added. It is also possible to instantiate an `InnerList` or an `Item`
+instance with included parameters using one of these named constructors:
 
 ```php
 use Bakame\Http\StructuredFields\InnerList;
 use Bakame\Http\StructuredFields\Item;
 
 //@type SfItemInput ByteSequence|Token|DateTimeInterface|Stringable|string|int|float|bool
 
-Item::from(SfItemInput $value, iterable<string, SfItemInput> $parameters = []): self;
-Item::fromPair(array{0:SfItemInput, 1:iterable<array{0:string, 1:SfItemInput}>} $pair): self;
+Item::fromAssociative(SfItemInput $value, iterable<string, SfItemInput>|Parameters $parameters = []): self;
+Item::fromPair(array{0:SfItemInput, 1:iterable<array{0:string, 1:SfItemInput}>|Parameters} $pair): self;
 
-InnerList::fromAssociative(iterable<string, SfItemInput> $parameters, ...$members): self;
-InnerList::fromPair(array{0:list<Item>, iterable<array{0:string, 1:SfItemInput}>} $pair): self;
+InnerList::fromAssociative(iterable<SfItemInput> $members, iterable<string, SfItemInput>|Parameters $parameters): self;
+InnerList::fromPair(array{0:iterable<SfItemInput>, iterable<array{0:string, 1:SfItemInput}>|Parameters} $pair): self;
 ```
 
 Both classes allow return their respective pair representation via the `toPair` method.
@@ -375,7 +378,7 @@ InnerList::toPair(): array{0:list<Item>, 1:Parameters}>};
 Item::toPair(): array{0:mixed, 1:Parameters}>};
 ```
 
-The `InnerList` and `Item` object provide additional modifying methods to help deal with parameters.
+Both objects provide additional modifying methods to help deal with parameters.
 You can attach and update the associated `Parameters` instance using the following methods:
 
 ```php

src/Dictionary.php

@@ -54,7 +54,7 @@ private static function filterMember(mixed $member): object
             $member instanceof ParameterAccess &&
             ($member instanceof MemberList || $member instanceof ValueAccess) => $member,
             is_iterable($member) => InnerList::from(...$member),
-            default => Item::from($member),
+            default => Item::fromAssociative($member),
         };
     }
 
@@ -112,7 +112,7 @@ public static function fromHttpValue(Stringable|string $httpValue): self
     {
         return new self((function (iterable $members) {
             foreach ($members as $key => $member) {
-                yield $key => is_array($member) ? InnerList::fromAssociative($member[1], ...$member[0]) : $member;
+                yield $key => is_array($member) ? InnerList::fromAssociative($member[0], $member[1]) : $member;
             }
         })(Parser::parseDictionary($httpValue)));
     }

src/DictionaryTest.php

@@ -17,8 +17,8 @@ final class DictionaryTest extends StructuredFieldTestCase
     #[Test]
     public function it_can_be_instantiated_with_an_collection_of_item_or_inner_list(): void
     {
-        $stringItem = Item::from('helloWorld');
-        $booleanItem = Item::from(true);
+        $stringItem = Item::fromAssociative('helloWorld');
+        $booleanItem = Item::fromAssociative(true);
         $arrayParams = ['string' => $stringItem, 'boolean' => $booleanItem];
         $instance = Dictionary::fromAssociative($arrayParams);
 
@@ -34,8 +34,8 @@ public function it_can_be_instantiated_with_an_collection_of_item_or_inner_list(
     #[Test]
     public function it_can_be_instantiated_with_key_value_pairs(): void
     {
-        $stringItem = Item::from('helloWorld');
-        $booleanItem = Item::from(true);
+        $stringItem = Item::fromAssociative('helloWorld');
+        $booleanItem = Item::fromAssociative(true);
         $arrayParams = [['string', $stringItem], ['boolean', $booleanItem]];
         $instance = Dictionary::fromPairs($arrayParams);
 
@@ -49,8 +49,8 @@ public function it_can_be_instantiated_with_key_value_pairs(): void
     #[Test]
     public function it_can_add_or_remove_members(): void
     {
-        $stringItem = Item::from('helloWorld');
-        $booleanItem = Item::from(true);
+        $stringItem = Item::fromAssociative('helloWorld');
+        $booleanItem = Item::fromAssociative(true);
         $arrayParams = ['string' => $stringItem, 'boolean' => $booleanItem];
         $instance = Dictionary::fromAssociative($arrayParams);
 
@@ -64,10 +64,10 @@ public function it_can_add_or_remove_members(): void
         self::assertFalse($deletedInstance->has('boolean'));
         self::assertFalse($deletedInstance->hasPair(1));
 
-        $appendInstance = $deletedInstance->append('foobar', Item::from('BarBaz'));
+        $appendInstance = $deletedInstance->append('foobar', Item::fromAssociative('BarBaz'));
         self::assertTrue($appendInstance->hasPair(1));
 
-        self::assertSame($appendInstance, $appendInstance->append('foobar', Item::from('BarBaz')));
+        self::assertSame($appendInstance, $appendInstance->append('foobar', Item::fromAssociative('BarBaz')));
 
         /** @var array{0:string, 1:Item} $foundItem */
         $foundItem = $appendInstance->pair(1);
@@ -119,15 +119,15 @@ public function it_fails_to_add_an_item_with_wrong_key(): void
     {
         $this->expectException(SyntaxError::class);
 
-        Dictionary::fromAssociative(['bébé'=> Item::from(false)]);
+        Dictionary::fromAssociative(['bébé'=> Item::fromAssociative(false)]);
     }
 
     #[Test]
     public function it_can_prepend_a_new_member(): void
     {
         $instance = Dictionary::create()
-            ->append('a', Item::from(false))
-            ->prepend('b', Item::from(true));
+            ->append('a', Item::fromAssociative(false))
+            ->prepend('b', Item::fromAssociative(true));
 
         self::assertSame('b, a=?0', (string) $instance);
     }
@@ -140,74 +140,74 @@ public function it_can_returns_the_container_member_keys(): void
         self::assertSame([], $instance->keys());
 
         $newInstance = $instance
-            ->append('a', Item::from(false))
-            ->prepend('b', Item::from(true));
+            ->append('a', Item::fromAssociative(false))
+            ->prepend('b', Item::fromAssociative(true));
 
         self::assertSame(['b', 'a'], $newInstance->keys());
     }
 
     #[Test]
     public function it_can_merge_one_or_more_instances_using_associative(): void
     {
-        $instance1 = Dictionary::fromAssociative(['a' => Item::from(false)]);
-        $instance2 = Dictionary::fromAssociative(['b' => Item::from(true)]);
-        $instance3 = Dictionary::fromAssociative(['a' => Item::from(42)]);
+        $instance1 = Dictionary::fromAssociative(['a' => Item::fromAssociative(false)]);
+        $instance2 = Dictionary::fromAssociative(['b' => Item::fromAssociative(true)]);
+        $instance3 = Dictionary::fromAssociative(['a' => Item::fromAssociative(42)]);
 
         $instance4 = $instance1->mergeAssociative($instance2, $instance3);
 
         self::assertCount(2, $instance4);
-        self::assertEquals(Item::from(42), $instance4->get('a'));
-        self::assertEquals(Item::from(true), $instance4->get('b'));
+        self::assertEquals(Item::fromAssociative(42), $instance4->get('a'));
+        self::assertEquals(Item::fromAssociative(true), $instance4->get('b'));
     }
 
     #[Test]
     public function it_can_merge_two_or_more_instances_to_yield_different_result(): void
     {
-        $instance1 = Dictionary::fromAssociative(['a' => Item::from(false)]);
-        $instance2 = Dictionary::fromAssociative(['b' => Item::from(true)]);
-        $instance3 = Dictionary::fromAssociative(['a' => Item::from(42)]);
+        $instance1 = Dictionary::fromAssociative(['a' => Item::fromAssociative(false)]);
+        $instance2 = Dictionary::fromAssociative(['b' => Item::fromAssociative(true)]);
+        $instance3 = Dictionary::fromAssociative(['a' => Item::fromAssociative(42)]);
 
         $instance4 = $instance3->mergeAssociative($instance2, $instance1);
 
         self::assertCount(2, $instance4);
-        self::assertEquals(Item::from(false), $instance4->get('a'));
-        self::assertEquals(Item::from(true), $instance4->get('b'));
+        self::assertEquals(Item::fromAssociative(false), $instance4->get('a'));
+        self::assertEquals(Item::fromAssociative(true), $instance4->get('b'));
     }
 
     #[Test]
     public function it_can_merge_without_argument_and_not_throw(): void
     {
-        self::assertCount(1, Dictionary::fromAssociative(['a' => Item::from(false)])->mergeAssociative());
+        self::assertCount(1, Dictionary::fromAssociative(['a' => Item::fromAssociative(false)])->mergeAssociative());
     }
 
     #[Test]
     public function it_can_merge_one_or_more_instances_using_pairs(): void
     {
-        $instance1 = Dictionary::fromPairs([['a', Item::from(false)]]);
-        $instance2 = Dictionary::fromPairs([['b', Item::from(true)]]);
-        $instance3 = Dictionary::fromPairs([['a', Item::from(42)]]);
+        $instance1 = Dictionary::fromPairs([['a', Item::fromAssociative(false)]]);
+        $instance2 = Dictionary::fromPairs([['b', Item::fromAssociative(true)]]);
+        $instance3 = Dictionary::fromPairs([['a', Item::fromAssociative(42)]]);
 
         $instance4 = $instance3->mergePairs($instance2, $instance1);
 
         self::assertCount(2, $instance4);
 
-        self::assertEquals(Item::from(false), $instance4->get('a'));
-        self::assertEquals(Item::from(true), $instance4->get('b'));
+        self::assertEquals(Item::fromAssociative(false), $instance4->get('a'));
+        self::assertEquals(Item::fromAssociative(true), $instance4->get('b'));
     }
 
     #[Test]
     public function it_can_merge_without_pairs_and_not_throw(): void
     {
-        $instance = Dictionary::fromAssociative(['a' => Item::from(false)]);
+        $instance = Dictionary::fromAssociative(['a' => Item::fromAssociative(false)]);
 
         self::assertCount(1, $instance->mergePairs());
     }
 
     #[Test]
     public function it_can_merge_dictionary_instances_via_pairs_or_associative(): void
     {
-        $instance1 = Dictionary::fromAssociative(['a' => Item::from(false)]);
-        $instance2 = Dictionary::fromAssociative(['b' => Item::from(true)]);
+        $instance1 = Dictionary::fromAssociative(['a' => Item::fromAssociative(false)]);
+        $instance2 = Dictionary::fromAssociative(['b' => Item::fromAssociative(true)]);
 
         $instance3 = clone $instance1;
         $instance4 = clone $instance2;
@@ -292,6 +292,6 @@ public function it_forbids_adding_members_using_the_array_access_interface(): vo
     {
         $this->expectException(LogicException::class);
 
-        Dictionary::fromPairs([['foobar', 'foobar'], ['zero', 0]])['foobar'] = Item::from(false);
+        Dictionary::fromPairs([['foobar', 'foobar'], ['zero', 0]])['foobar'] = Item::fromAssociative(false);
     }
 }

src/InnerList.php

@@ -45,7 +45,7 @@ private static function filterMember(mixed $member): object
     {
         return match (true) {
             $member instanceof ValueAccess && $member instanceof ParameterAccess => $member,
-            !$member instanceof StructuredField => Item::from($member),
+            !$member instanceof StructuredField => Item::fromAssociative($member),
             default => throw new InvalidArgument('Expecting a "'.ValueAccess::class.'" instance; received a "'.$member::class.'" instead.'),
         };
     }
@@ -86,12 +86,11 @@ public static function fromPair(array $pair): self
     /**
      * Returns a new instance with an iter.
      *
+     * @param iterable<SfItemInput> $members
      * @param iterable<string, SfItemInput> $parameters
      */
-    public static function fromAssociative(
-        iterable $parameters,
-        StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members
-    ): self {
+    public static function fromAssociative(iterable $members, iterable $parameters = []): self
+    {
         return new self(Parameters::fromAssociative($parameters), $members);
     }
 
@@ -102,9 +101,7 @@ public static function fromAssociative(
      */
     public static function fromHttpValue(Stringable|string $httpValue): self
     {
-        [$members, $parameters] = Parser::parseInnerList($httpValue);
-
-        return self::fromAssociative($parameters, ...$members);
+        return self::fromAssociative(...Parser::parseInnerList($httpValue));
     }
 
     public function parameters(): Parameters