Adding ParameterAccess::parameter method

Author: nyamsprod

CHANGELOG.md

@@ -6,6 +6,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Added
 
+- `ParameterAccess::parameter` to ease parameter members value access.
 - **[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.

README.md

@@ -180,12 +180,13 @@ Last but not least you can attach and update to `Item` and `InnerList` instances
 following methods:
 
 ```php
-$field->withParameters(Parameters $parameters): static;
+$field->parameter($key): mixed|null;
 $field->addParameter($key, $value): static;
 $field->appendParameter($key, $value): static;
 $field->prependParameter($key, $value): static;
 $field->withoutParameters(...$keys): static;
 $field->withoutAllParameters($): static;
+$field->withParameters(Parameters $parameters): static;
 ```
 
 ### Item and RFC Data Types
@@ -217,11 +218,10 @@ $item = Item::fromPair([
         ["a", ByteSequence::fromDecoded("Hello World")],
     ]
 ]);
-$item->value();                    // returns "hello world"
-$item->type();                     // returns Type::String
-$item->parameters()["a"]->type();  // returns Type::ByteSequence
-$item->parameters()["a"]->value(); // returns StructuredFields\ByteSequence::fromDecoded('Hello World');
-echo $item->toHttpValue();         // returns "hello world";a=:SGVsbG8gV29ybGQ=:
+$item->value();            // returns "hello world"
+$item->type();             // returns Type::String
+$item->parameters("a");    // returns StructuredFields\ByteSequence::fromDecoded('Hello World');
+echo $item->toHttpValue(); // returns "hello world";a=:SGVsbG8gV29ybGQ=:
 ```
 
 Once again it is possible to simplify this code using the following technique:
@@ -233,11 +233,10 @@ use Bakame\Http\StructuredFields\Item;
 $item = Item::from("hello world", [
     "a" => Item::fromDecodedByteSequence("Hello World")
 ]);
-$item->value();                    // returns "hello world"
-$item->type();                     // returns Type::String
-$item->parameters()["a"]->value(); // returns StructuredFields\ByteSequence::fromDecoded('Hello World');
-$item->parameters()["a"]->type();  // returns Type::ByteSequence
-echo $item->toHttpValue();         // returns "hello world";a=:SGVsbG8gV29ybGQ=:
+$item->value();            // returns "hello world"
+$item->type();             // returns Type::String
+$item->parameters("a");    // returns StructuredFields\ByteSequence::fromDecoded('Hello World');
+echo $item->toHttpValue(); // returns "hello world";a=:SGVsbG8gV29ybGQ=:
 ```
 
 The RFC define two (2) specific data types that can not be represented by PHP default type system, for them, we define
@@ -298,8 +297,8 @@ use Bakame\Http\StructuredFields\Item;
 $value = Item::from("Hello world", [
     'a' => 'foobar',
 ]);
-$value->parameters()->has('b');     // return false
-$value->parameters()['a'];          // return Item::from('foobar')
+$value->parameters('b');            // return null
+$value->parameters('a');            // return 'foobar'
 $value->parameters()['a'] = 23      // triggers a ForbiddenOperation exception
 unset($value->parameters()['a']);   // triggers a ForbiddenOperation exception
 ```

src/InnerList.php

@@ -75,6 +75,15 @@ public function parameters(): Parameters
         return $this->parameters;
     }
 
+    public function parameter(string $key): mixed
+    {
+        if ($this->parameters->has($key)) {
+            return $this->parameters->get($key)->value();
+        }
+
+        return null;
+    }
+
     public function addParameter(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): static
     {
         return $this->withParameters($this->parameters()->add($key, $member));

src/InnerListTest.php

@@ -215,6 +215,8 @@ public function it_can_create_via_parameters_access_methods_a_new_object(): void
         self::assertSame($instance1, $instance4);
         self::assertFalse($instance5->parameters()->hasMembers());
         self::assertTrue($instance6->parameters()->hasNoMembers());
+        self::assertTrue($instance1->parameter('a'));
+        self::assertNull($instance5->parameter('a'));
     }
 
     #[Test]

src/Item.php

@@ -215,6 +215,15 @@ public function parameters(): Parameters
         return $this->parameters;
     }
 
+    public function parameter(string $key): mixed
+    {
+        if ($this->parameters->has($key)) {
+            return $this->parameters->get($key)->value();
+        }
+
+        return null;
+    }
+
     public function addParameter(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): static
     {
         return $this->withParameters($this->parameters()->add($key, $member));

src/ItemTest.php

@@ -358,6 +358,8 @@ public function it_can_create_via_parameters_access_methods_a_new_object(): void
         self::assertNotSame($instance1, $instance3);
         self::assertEquals($instance1->value(), $instance3->value());
         self::assertSame($instance1, $instance4);
+        self::assertTrue($instance1->parameter('a'));
+        self::assertNull($instance5->parameter('a'));
         self::assertTrue($instance5->parameters()->hasNoMembers());
         self::assertTrue($instance6->parameters()->hasNoMembers());
     }

src/ParameterAccess.php

@@ -4,13 +4,23 @@
 
 namespace Bakame\Http\StructuredFields;
 
+/**
+ * @phpstan-import-type DataType from Value
+ */
 interface ParameterAccess
 {
     /**
      * Returns a copy of the associated parameter instance.
      */
     public function parameters(): Parameters;
 
+    /**
+     * Returns the member value or null if no members value exists.
+     *
+     * @return DataType|null
+     */
+    public function parameter(string $key): mixed;
+
     /**
      * Adds a member if its key is not present at the of the associated parameter instance or update the instance at the given key.
      *