Add parser public API

Author: nyamsprod

CHANGELOG.md

@@ -16,6 +16,18 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - `ParameterAccess::replaceParamater`
 - `ParameterAccess::withoutParametersByKeys`
 - `ParameterAccess::withoutParametersByIndices`
+- `ItemParser` interface to return an array representation of a Structured Field as an item.
+- `ParametersParser` interface to return an array representation of a Structured Field parameter container.
+- `DictionaryParser` interface to return an array representation of a Structured Field dictionary container.
+- `ListParser` interface to return an array representation of a Structured Field list container.
+- `InnerListParser` interface to return an array representation of a Structured Field inner list container.
+- `ValueParser` interface to return a PHP type of a Structured Field Value string representation.
+- `Parser` is now part of the public API
+- `Item::fromHttpValue` now has an optional second parameter to shift the parser implementation used
+- `Parameters::fromHttpValue` now has an optional second parameter to shift the parser implementation used
+- `Dictionary::fromHttpValue` now has an optional second parameter to shift the parser implementation used
+- `OuterList::fromHttpValue` now has an optional second parameter to shift the parser implementation used
+- `InnerList::fromHttpValue` now has an optional second parameter to shift the parser implementation used
 
 ### Fixed
 

README.md

@@ -113,6 +113,56 @@ All five (5) structured data type as defined in the RFC are provided inside the
 - `OuterList` (named `List` in the RFC but renamed in the package because `list` is a reserved word in PHP.)
 - `InnerList`
 
+#### Advance usage
+
+In order to allow:
+
+- clearer decoupling betwen parsing and objet building
+- different parsers implementations
+- improve the package usage in testing.
+
+Starting with version `1.1` the internal parser has been made public. The class exposes
+the following method each belonging to a different contract or interface.
+
+```php
+Parser::parseValue(Stringable|string $httpValue): ByteSequence|Token|DateTimeImmutable|string|int|float|bool;
+Parser::parseItem(Stringable|string $httpValue): array;
+Parser::parseParameters(Stringable|string $httpValue): array;
+Parser::parseInnerList(Stringable|string $httpValue): array;
+Parser::parseList(Stringable|string $httpValue): array;
+Parser::parseDictionary(Stringable|string $httpValue): array;
+```
+
+While the provided default `Parser` class implements all these methods
+you are free to only implement the methods you need.
+
+```php
+use Bakame\Http\StructuredFields\Parser;
+
+$parser = new Parser();
+$parser->parseValue('text/csv'); //returns Token::fromString('text/csv')
+$parser->parseItem('@1234567890;file=24'); 
+//returns an array
+//  [
+//    new DateTimeImmutable('@1234567890'),
+//    ['file' => 24],
+//  ]
+```
+
+Each `fromHttpValue` method signature has been updated to take a second optional argument
+that represents the parser interface to use in order to allow parsing of the HTTP string
+representation value.
+
+By default, if no parser is provided, the package will default to use the package `Parser` class,
+
+```php
+Item::fromHttpValue(Stringable|string $httpValue, ItemParser $parser = new Parser()): Item;
+InnerList::fromHttpValue(Stringable|string $httpValue, InnerListParser $parser = new Parser()): InnerList;
+Dictionary::fromHttpValue(Stringable|string $httpValue, DictionaryParser $parser = new Parser()): Dictionary;
+OuterList::fromHttpValue(Stringable|string $httpValue, ListParser $parser = new Parser()): OuterList;
+Parameters::fromHttpValue(Stringable|string $httpValue, ParametersParser $parser = new Parser()): Parameters;
+```
+
 ### Accessing Structured Fields Values
 
 #### RFC Value type

src/Dictionary.php

@@ -108,17 +108,17 @@ public static function fromPairs(iterable $pairs): self
      *
      * @throws SyntaxError If the string is not a valid
      */
-    public static function fromHttpValue(Stringable|string $httpValue): self
+    public static function fromHttpValue(Stringable|string $httpValue, DictionaryParser $parser = new Parser()): self
     {
         $converter = fn (array $member): InnerList|Item => match (true) {
             is_array($member[0]) => InnerList::fromAssociative(
                 array_map(fn (array $item) => Item::fromAssociative(...$item), $member[0]),
                 $member[1]
             ),
-            default => Item::fromAssociative($member[0], $member[1]),
+            default => Item::fromAssociative(...$member),
         };
 
-        return new self(array_map($converter, Parser::parseDictionary($httpValue)));
+        return new self(array_map($converter, $parser->parseDictionary($httpValue)));
     }
 
     public function toHttpValue(): string

src/DictionaryParser.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bakame\Http\StructuredFields;
+
+use Stringable;
+
+/**
+ * @phpstan-import-type SfType from StructuredField
+ */
+interface DictionaryParser
+{
+    /**
+     * Returns an ordered map represented as a PHP associative array from an HTTP textual representation.
+     *
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.2
+     *
+     * @return array<string, array{0:SfType|array<array{0:SfType, 1:array<string, SfType>}>, 1:array<string, SfType>}>
+     */
+    public function parseDictionary(Stringable|string $httpValue): array;
+}

src/InnerList.php

@@ -59,12 +59,12 @@ private static function filterMember(mixed $member): object
      *
      * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.1
      */
-    public static function fromHttpValue(Stringable|string $httpValue): self
+    public static function fromHttpValue(Stringable|string $httpValue, InnerListParser $parser = new Parser()): self
     {
-        [$membersList, $parameters] = Parser::parseInnerList($httpValue);
+        [$members, $parameters] = $parser->parseInnerList($httpValue);
 
         return new self(
-            array_map(fn (array $member): Item => Item::fromAssociative(...$member), $membersList),
+            array_map(fn (array $member): Item => Item::fromAssociative(...$member), $members),
             Parameters::fromAssociative($parameters)
         );
     }

src/InnerListParser.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bakame\Http\StructuredFields;
+
+use Stringable;
+
+/**
+ * @phpstan-import-type SfType from StructuredField
+ */
+interface InnerListParser
+{
+    /**
+     * Returns an inner list represented as a PHP list array from an HTTP textual representation.
+     *
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.1.2
+     *
+     * @return array{0:array<array{0:SfType, 1:array<string, SfType>}>, 1:array<string, SfType>}
+     */
+    public function parseInnerList(Stringable|string $httpValue): array;
+}

src/Item.php

@@ -32,9 +32,9 @@ private function __construct(
      *
      * @throws SyntaxError If the HTTP value can not be parsed
      */
-    public static function fromHttpValue(Stringable|string $httpValue): self
+    public static function fromHttpValue(Stringable|string $httpValue, ItemParser $parser = new Parser()): self
     {
-        return self::fromAssociative(...Parser::parseItem($httpValue));
+        return self::fromAssociative(...$parser->parseItem($httpValue));
     }
 
     /**

src/ItemParser.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bakame\Http\StructuredFields;
+
+use Stringable;
+
+/**
+ * @phpstan-import-type SfType from StructuredField
+ */
+interface ItemParser
+{
+    /**
+     * Returns an Item represented as a PHP list array from an HTTP textual representation.
+     *
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#name-parsing-an-item
+     *
+     * @return array{0:SfType, 1:array<string, SfType>}
+     */
+    public function parseItem(Stringable|string $httpValue): array;
+}

src/ListParser.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bakame\Http\StructuredFields;
+
+use Stringable;
+
+/**
+ * @phpstan-import-type SfType from StructuredField
+ */
+interface ListParser
+{
+    /**
+     * Returns an ordered list represented as a PHP list array from an HTTP textual representation.
+     *
+     * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.1
+     *
+     * @return array<array{0:SfType|array<array{0:SfType, 1:array<string, SfType>}>, 1:array<string, SfType>}>
+     */
+    public function parseList(Stringable|string $httpValue): array;
+}

src/OuterList.php

@@ -60,17 +60,17 @@ private static function filterMember(mixed $member): object
      *
      * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.1
      */
-    public static function fromHttpValue(Stringable|string $httpValue): self
+    public static function fromHttpValue(Stringable|string $httpValue, ListParser $parser = new Parser()): self
     {
         $converter = fn (array $member): InnerList|Item => match (true) {
             is_array($member[0]) => InnerList::fromAssociative(
                 array_map(fn (array $item) => Item::fromAssociative(...$item), $member[0]),
                 $member[1]
             ),
-            default => Item::fromAssociative($member[0], $member[1]),
+            default => Item::fromAssociative(...$member),
         };
 
-        return new self(...array_map($converter, Parser::parseList($httpValue)));
+        return new self(...array_map($converter, $parser->parseList($httpValue)));
     }
 
     /**