Introduce ParameterAccess::parameterByIndex

Author: nyamsprod

CHANGELOG.md

@@ -6,11 +6,11 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Added
 
-- None
+- `Item::parameterByOffset` and `InnerList::parameterByOffset` tu returns the parameter as a tuple.
 
 ### Fixed
 
-- `Item::parameter` and `InnerList::parameter` now supports accessing parameters value per index.
+- `Parser` class is no longer internal
 
 ### Deprecated
 

README.md

@@ -263,11 +263,13 @@ use Bakame\Http\StructuredFields\Parameters;
 
 $field->parameter(string $key): ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|bool|null;
 $field->parameters(): Parameters;
+$field->parameterByIndex(int $index): array{0:string, 1:ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|boo}|array{}
 InnerList::toPair(): array{0:list<Item>, 1:Parameters}>};
 Item::toPair(): array{0:ByteSequence|Token|DateTimeImmutable|Stringable|string|int|float|bool, 1:Parameters}>};
 ```
 
-**The `parameter` method will return `null` if no value is found for the given index.**
+**The `parameter` method will return `null` if no value is found for the given key.**
+**The `parameterByIndex` method is added in `version 1.1.0` and returns an empty array if no parameter is found for the given index.**
 
 ### Building and Updating Structured Fields Values
 
@@ -525,6 +527,22 @@ echo InnerList::new('foo', 'bar')
 // ("foo" "bar");expire=@1681538756;path="/";max-age=2500
 ```
 
+### Advanced usages
+
+Starting with version `1.1.0` the parser is made public with the following static methods:
+
+- `Parser::parseList(Stringable|String $value): array`
+- `Parser::parseInnerList(Stringable|String $value): array`
+- `Parser::parseDictionary(Stringable|String $value): array`
+- `Parser::parseItem(Stringable|String $value): array`
+- `Parser::parseParameters(Stringable|String $value): array`
+
+All these static methods parse the HTTP Header string value and return a `array` structure
+representing the parsed string. It is possible to use this representation if you want
+to build your own structure field objects. Those methods are the ones used by all the 
+`fromHttpValue` named constructors to generate `StructuredField` instances from their
+returned `array`.
+
 ## Contributing
 
 Contributions are welcome and will be fully credited. Please see [CONTRIBUTING](.github/CONTRIBUTING.md) and [CODE OF CONDUCT](.github/CODE_OF_CONDUCT.md) for details.

src/InnerList.php

@@ -135,18 +135,29 @@ public function parameters(): Parameters
         return $this->parameters;
     }
 
-    public function parameter(string|int $key): Token|ByteSequence|DateTimeImmutable|int|float|string|bool|null
+    public function parameter(string $key): Token|ByteSequence|DateTimeImmutable|int|float|string|bool|null
     {
         try {
-            return match (true) {
-                is_int($key) => $this->parameters->pair($key)[1]->value(),
-                default => $this->parameters->get($key)->value(),
-            };
+            return $this->parameters->get($key)->value();
         } catch (StructuredFieldError) {
             return null;
         }
     }
 
+    /**
+     * @return array{0:string, 1:Token|ByteSequence|DateTimeImmutable|int|float|string|bool}|array{}
+     */
+    public function parameterByIndex(int $index): array
+    {
+        try {
+            $tuple = $this->parameters->pair($index);
+
+            return [$tuple[0], $tuple[1]->value()];
+        } catch (StructuredFieldError) {
+            return [];
+        }
+    }
+
     public function count(): int
     {
         return count($this->members);

src/InnerListTest.php

@@ -132,9 +132,9 @@ public function it_can_access_its_parameter_values(): void
 
         self::assertSame('bar', $instance->parameters()->get('foo')->value());
         self::assertSame('bar', $instance->parameter('foo'));
-        self::assertSame('bar', $instance->parameter(0));
+        self::assertSame(['foo', 'bar'], $instance->parameterByIndex(0));
         self::assertNull($instance->parameter('non-existing-key'));
-        self::assertNull($instance->parameter(-42));
+        self::assertSame([], $instance->parameterByIndex(42));
     }
 
     #[Test]

src/Item.php

@@ -219,18 +219,29 @@ public function parameters(): Parameters
         return $this->parameters;
     }
 
-    public function parameter(string|int $key): Token|ByteSequence|DateTimeImmutable|int|float|string|bool|null
+    public function parameter(string $key): Token|ByteSequence|DateTimeImmutable|int|float|string|bool|null
     {
         try {
-            return match (true) {
-                is_int($key) => $this->parameters->pair($key)[1]->value(),
-                default => $this->parameters->get($key)->value(),
-            };
+            return $this->parameters->get($key)->value();
         } catch (StructuredFieldError) {
             return null;
         }
     }
 
+    /**
+     * @return array{0:string, 1:Token|ByteSequence|DateTimeImmutable|int|float|string|bool}|array{}
+     */
+    public function parameterByIndex(int $index): array
+    {
+        try {
+            $tuple = $this->parameters->pair($index);
+
+            return [$tuple[0], $tuple[1]->value()];
+        } catch (StructuredFieldError) {
+            return [];
+        }
+    }
+
     /**
      * Serialize the Item value according to RFC8941.
      *

src/ItemTest.php

@@ -429,11 +429,11 @@ public function it_can_create_via_parameters_access_methods_a_new_object(): void
         self::assertEquals($instance1->value(), $instance3->value());
         self::assertSame($instance1, $instance4);
         self::assertTrue($instance1->parameter('a'));
-        self::assertTrue($instance1->parameter(0));
+        self::assertSame(['a', true], $instance1->parameterByIndex(0));
         self::assertNull($instance5->parameter('a'));
         self::assertTrue($instance5->parameters()->hasNoMembers());
         self::assertTrue($instance6->parameters()->hasNoMembers());
         self::assertNull($instance1->parameter('non-existing-key'));
-        self::assertNull($instance1->parameter(-42));
+        self::assertSame([], $instance1->parameterByIndex(42));
     }
 }

src/ParameterAccess.php

@@ -8,6 +8,8 @@
 
 /**
  * @phpstan-import-type SfItem from StructuredField
+ *
+ * @method array{0:string, 1:Token|ByteSequence|DateTimeImmutable|int|float|string|bool}|array{} parameterByIndex(int $index) returns the tuple representation of the parameter
  */
 interface ParameterAccess
 {

src/Parser.php

@@ -22,9 +22,6 @@
  *
  * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2
  *
- * @internal Use Dictionary::fromHttpValue(), Parameters::fromHttpValue(),
- *               OuterList::fromHttpValue(), InnerList::fromHttpValue() or Item::fromHttpValue() instead
- *
  * @phpstan-import-type SfType from StructuredField
  */
 final class Parser