Simplify Public API

Author: nyamsprod

CHANGELOG.md

@@ -31,6 +31,8 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - **[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`.
+- **[BC Break]**  remove the `InnerList::fromList`, use `InnerList::from` instead.
+- **[BC Break]**  remove the `OuterList::fromList`, use `OuterList::from` instead.
 
 ## [0.7.0] - 2023-02-06
 

README.md

@@ -7,10 +7,10 @@
 [![Total Downloads](https://img.shields.io/packagist/dt/bakame/http-structured-fields.svg?style=flat-square)](https://packagist.org/packages/bakame/http-structured-fields)
 [![Sponsor development of this project](https://img.shields.io/badge/sponsor%20this%20package-%E2%9D%A4-ff69b4.svg?style=flat-square)](https://github.com/sponsors/nyamsprod)
 
-The package uses value objects to parse, serialize, build and update [HTTP Structured Fields][1] in PHP.
+`bakame/http-structured-fields` is a framework-agnostic PHP library that allows you to parse, serialize and build HTTP Structured Fields in PHP according to the [RFC][1].
 
 HTTP Structured fields are intended for use for new HTTP fields that wish to use a common syntax that is
-more restrictive than traditional HTTP field values or could be used to [retrofit current fields][2] to
+more restrictive than traditional HTTP field values or could be used to retrofit current fields value to
 have them compliant with the new syntax.
 
 ```php
@@ -52,45 +52,65 @@ echo $list[-1]->value(); // returns '/member/*/comments'
 
 ### Parsing and Serializing Structured Fields
 
-To parse the string representation of an HTTP field you must use the `fromHttpValue`
-named constructor provided to all the immutable value objects:
+Once the library is installed parsing the header value is done via one of the package value object via its `fromHttpValue`
+named constructor as shown below:
 
 ```php
-use Bakame\Http\StructuredFields\Dictionary;
 
-$dictionary = Dictionary::fromHttpValue("a=?0,   b,   c=?1; foo=bar");
+declare(strict_types=1);
+
+namespace MyApp;
+
+require 'vendor/autoload.php';
+
+use Bakame\Http\StructuredFields\Item;
+
+//the HTTP request object is given by your application
+// or any given framework or package.
+//We use a PSR-7 Request object in this example
+
+$headerLine = $request->getHeaderLine('foo');
+$field = Item::fromHttpValue($headerLine);
+$field->value();          // returns the found token value
+$field->parameter('baz'); // returns the value of the parameter or null if the parameter is not defined.
 ```
 
-`fromHttpValue` returns an instance of the `Bakame\Http\StructuredFields\StructuredField` interface.
+The `fromHttpValue` method returns an instance of the `Bakame\Http\StructuredFields\StructuredField` interface.
 The interface provides a way to serialize the value object into a normalized RFC compliant HTTP field
 string value using the `toHttpValue` method.
 
 To ease integration with current PHP frameworks and packages working with HTTP headers and trailers,
-each value object also exposes the `Stringable` interface method `__toString`,
-an alias of the `toHttpValue` method.
+each value object also exposes the `Stringable` interface method `__toString` as an alias 
+of the `toHttpValue` method.
 
 ````php
-use Bakame\Http\StructuredFields\OuterList;
+use Bakame\Http\StructuredFields\Item;
 
-$list = OuterList::fromHttpValue('("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1');
-echo $list->toHttpValue(); // '("foo";a=1;b=2);lvl=5, ("bar" "baz");lvl=1'
-echo $list;                // '("foo";a=1;b=2);lvl=5, ("bar" "baz");lvl=1'
+$bar = Item::fromToken('bar')->addParameter('baz', Item::from(42));
+echo $bar->toHttpValue(); // return 'bar;baz=42'   
+
+//the HTTP response object is given by your application
+// or any given framework or package.
+//We use Symfony Response object in this example
+$newResponse = $response->headers->set('foo', $bar->toHttpValue());
+//or
+$newResponse = $response->headers->set('foo', $bar);
 ````
 
-The library provides currently five (5) immutable value objects define inside the `Bakame\Http\StructuredFields`
-namespace 
+The library provides all five (5) structured defined in the RFC inside the `Bakame\Http\StructuredFields`
+namespace.
 
 - `Item`;
-- `Dictionary` and `Parameters` as 2 Ordered Map Containers;
-- `OuterList` and `InnerList` as 2 List Containers ;
+- `Dictionary` and `Parameters` as 2 Ordered map Containers;
+- `OuterList` and `InnerList` as 2 list Containers ;
 
-they all implement the `StructuredField` interface and expose a `fromHttpValue` named constructor:
+They all implement the `StructuredField` interface and expose a `fromHttpValue` named constructor:
 
 ### Building and Updating Structured Fields Values
 
 Every value object can be used as a builder to create an HTTP field value.
 
-For instance, `Dictionary` and `Parameters` can be build with an associative iterable as shown below
+The `Dictionary` and `Parameters` instances can be build with an associative iterable structure as shown below
 
 ```php
 use Bakame\Http\StructuredFields\Dictionary;
@@ -105,7 +125,7 @@ echo $value->toHttpValue(); //"b=?0, a=bar;baz=42, c=@1671800423"
 echo $value;                //"b=?0, a=bar;baz=42, c=@1671800423"
 ```
 
-Or with an iterable structure of pairs as described in the RFC:
+Or with an iterable structure of pairs as per defined in the RFC:
 
 ```php
 use Bakame\Http\StructuredFields\Parameters;
@@ -120,7 +140,7 @@ echo $value->toHttpValue(); //;b=?0;a=bar;c=@1671800423
 echo $value;                //;b=?0;a=bar;c=@1671800423
 ```
 
-If builder methods are preferred, 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:
 
 ```php
 use Bakame\Http\StructuredFields\Dictionary;
@@ -129,7 +149,7 @@ use Bakame\Http\StructuredFields\Token;
 
 $bar = Item::fromToken('bar')
     ->addParameter('baz', Item::from(42));
-$dictBuilder = Dictionary::create()
+$value = Dictionary::create()
     ->add('a', $bar)
     ->prepend('b', Item::from(false))
     ->append('c', Item::from(new DateTimeImmutable('2022-12-23 13:00:23')))
@@ -200,28 +220,28 @@ Items can have different types that are translated to PHP using:
 
 The table below summarizes the item value type.
 
-| HTTP DataType | Package Data Type                                      | Package Enum Type    |
-|---------------|--------------------------------------------------------|----------------------|
-| Integer       | `int`                                                  | `Type::Integer`      |
-| Decimal       | `float`                                                | `Type::Decimal`      |
-| String        | `string` or `Stringable` class                         | `Tyoe::String`       |
-| Boolean       | `bool`                                                 | `Type::Boolean`      |
-| Token         | class `Token`                                          | `Type::Token`        |
-| Byte Sequence | class `ByteSequence`                                   | `Type::ByteSequence` |
-| Date          | class `DateTimeImmutable` or `DateTimeInterface` class | `Type::Date`         |
+| HTTP DataType | Package Data Type              | Package Enum Type    |
+|---------------|--------------------------------|----------------------|
+| Integer       | `int`                          | `Type::Integer`      |
+| Decimal       | `float`                        | `Type::Decimal`      |
+| String        | `string` or `Stringable` class | `Tyoe::String`       |
+| Boolean       | `bool`                         | `Type::Boolean`      |
+| Token         | class `Token`                  | `Type::Token`        |
+| Byte Sequence | class `ByteSequence`           | `Type::ByteSequence` |
+| Date          | class `DateTimeImmutable`      | `Type::Date`         |
 
 ```php
 use Bakame\Http\StructuredFields\ByteSequence;
 use Bakame\Http\StructuredFields\Item;
 
 $item = Item::fromPair([
     "hello world", [
-        ["a", ByteSequence::fromDecoded("Hello World")],
+        ["a", Item::from(ByteSequence::fromDecoded("Hello World"))],
     ]
 ]);
 $item->value();            // returns "hello world"
 $item->type();             // returns Type::String
-$item->parameters("a");    // returns StructuredFields\ByteSequence::fromDecoded('Hello World');
+$item->parameters("a");    // returns ByteSequence::fromDecoded('Hello World');
 echo $item->toHttpValue(); // returns "hello world";a=:SGVsbG8gV29ybGQ=:
 ```
 
@@ -276,10 +296,10 @@ 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::fromDate(DateTimeInterface $datetime): self;
 Item::fromTimestamp(int $value): self;
-Item::fromDateFormat(string $dateFormat, string $dateString): self;
-Item::fromDateFormat(string $dateString, DateTimeZone|string|null $timezone): self;
+Item::fromDateFormat(string $format, string $datetime): self;
+Item::fromDateString(string $datetime, DateTimeZone|string|null $timezone): self;
 ```
 
 ### Accessing members of Structured Fields Containers.

composer.json

@@ -30,7 +30,7 @@
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^v3.14.3",
         "httpwg/structured-field-tests": "*@dev",
-        "phpstan/phpstan": "^1.10.4",
+        "phpstan/phpstan": "^1.10.5",
         "phpstan/phpstan-strict-rules": "^1.5.0",
         "phpstan/phpstan-phpunit": "^1.3.10",
         "phpstan/phpstan-deprecation-rules": "^1.1.2",

src/Dictionary.php

@@ -48,7 +48,7 @@ private static function filterMember(iterable|StructuredField|Token|ByteSequence
         return match (true) {
             ($member instanceof MemberList && $member instanceof ParameterAccess),
             $member instanceof Value => $member,
-            is_iterable($member) => InnerList::fromList($member),
+            is_iterable($member) => InnerList::from(...$member),
             default => Item::from($member),
         };
     }
@@ -107,7 +107,7 @@ public static function fromHttpValue(Stringable|string $httpValue): self
     {
         return new self((function (iterable $pairs) {
             foreach ($pairs as $key => $value) {
-                yield $key => is_array($value) ? InnerList::fromList(...$value) : $value;
+                yield $key => is_array($value) ? InnerList::from(...$value[0])->withParameters(Parameters::fromAssociative($value[1])) : $value;
             }
         })(Parser::parseDictionary($httpValue)));
     }

src/InnerList.php

@@ -42,15 +42,6 @@ public static function from(Value|Token|ByteSequence|DateTimeInterface|Stringabl
         return new self(Parameters::create(), $members);
     }
 
-    /**
-     * @param iterable<Value|DataType> $members
-     * @param iterable<string, Value|DataType> $parameters
-     */
-    public static function fromList(iterable $members = [], iterable $parameters = []): self
-    {
-        return new self(Parameters::fromAssociative($parameters), $members);
-    }
-
     private static function filterMember(StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): Value
     {
         return match (true) {
@@ -67,7 +58,10 @@ private static function filterMember(StructuredField|Token|ByteSequence|DateTime
      */
     public static function fromHttpValue(Stringable|string $httpValue): self
     {
-        return self::fromList(...Parser::parseInnerList($httpValue));
+        [$members, $parameters] = [...Parser::parseInnerList($httpValue)];
+
+        return self::from(...$members)
+            ->withParameters(Parameters::fromAssociative($parameters));
     }
 
     public function parameters(): Parameters

src/InnerListTest.php

@@ -16,7 +16,8 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
         $stringItem = Item::from('helloWorld');
         $booleanItem = Item::from(true);
         $arrayParams = [$stringItem, $booleanItem];
-        $instance = InnerList::fromList($arrayParams, Parameters::fromAssociative(['test' => Item::from(42)]));
+        $instance = InnerList::from(...$arrayParams)
+            ->withParameters(Parameters::fromAssociative(['test' => Item::from(42)]));
 
         self::assertSame($stringItem, $instance->get(0));
         self::assertTrue($instance->hasMembers());
@@ -30,7 +31,7 @@ public function it_can_add_or_remove_members(): void
     {
         $stringItem = Item::from('helloWorld');
         $booleanItem = Item::from(true);
-        $instance = InnerList::fromList([$stringItem, $booleanItem]);
+        $instance = InnerList::from($stringItem, $booleanItem);
 
         self::assertCount(2, $instance);
         self::assertTrue($instance->has(1));
@@ -116,17 +117,18 @@ public function it_fails_to_return_an_member_with_invalid_index(): void
     #[Test]
     public function it_can_access_its_parameter_values(): void
     {
-        $instance = InnerList::fromList([false], ['foo' => 'bar']);
+        $instance = InnerList::from(false)->addParameter('foo', 'bar');
 
         self::assertSame('bar', $instance->parameters()->get('foo')->value());
+        self::assertSame('bar', $instance->parameter('foo'));
     }
 
     #[Test]
     public function it_fails_to_access_unknown_parameter_values(): void
     {
         $this->expectException(StructuredFieldError::class);
 
-        InnerList::fromList([false], ['foo' => 'bar'])->parameters()->get('bar')->value();
+        InnerList::from(false)->parameters()->get('bar')->value();
     }
 
     #[Test]
@@ -179,7 +181,7 @@ public function it_can_access_the_item_value(): void
     {
         $token = Token::fromString('token');
         $input = ['foobar', 0, false, $token];
-        $structuredField = InnerList::fromList($input);
+        $structuredField = InnerList::from(...$input);
 
         self::assertFalse($structuredField->get(2)->value());
         self::assertEquals($token, $structuredField->get(-1)->value());
@@ -188,7 +190,7 @@ public function it_can_access_the_item_value(): void
     #[Test]
     public function it_can_create_via_with_parameters_method_a_new_object(): void
     {
-        $instance1 = InnerList::fromList([Token::fromString('babayaga'), 'a', true], ['a' => true]);
+        $instance1 = InnerList::from(Token::fromString('babayaga'), 'a', true)->addParameter('a', true);
         $instance2 = $instance1->withParameters(Parameters::fromAssociative(['a' => true]));
         $instance3 = $instance1->withParameters(Parameters::fromAssociative(['a' => false]));
 
@@ -200,7 +202,7 @@ public function it_can_create_via_with_parameters_method_a_new_object(): void
     #[Test]
     public function it_can_create_via_parameters_access_methods_a_new_object(): void
     {
-        $instance1 = InnerList::fromList([Token::fromString('babayaga'), 'a', true], ['a' => true]);
+        $instance1 = InnerList::from(Token::fromString('babayaga'), 'a', true)->withParameters(Parameters::fromAssociative(['a' => true]));
         $instance2 = $instance1->appendParameter('a', true);
         $instance7 = $instance1->addParameter('a', true);
         $instance3 = $instance1->prependParameter('a', false);