Use readonly properties for parameters and Item value

Author: nyamsprod

CHANGELOG.md

@@ -6,34 +6,39 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Added
 
-- `Item::exchangeParameters` to fully replace the `Item` associated parameters
-- `InnerList::exchangeParameters` to fully replace the `InnerList` associated parameters
-- `InnerList::from` named constructor which accepts a variadic list of members items
+- `Item::value` is a public readonly property that gives access to the item value
+- `Item::parameters` is a public readonly property that gives access to the item parameters
+- `InnerList::parameters` is a public readonly property that gives access to the list parameters
 - `OrderedList::from` named constructor which accepts a variadic list of members items
 - `Token::fromString` named constructor which accepts `string` and `Stringable` object
 - `Parameter::values` returns an array of all the values contained inside the `Parameters` instance
-- [BC Break] `InnerList::fromList` to replace `InnerList::fromMembers`
-- [BC Break] `OrderedList::fromList` to replace `OrderedList::fromMembers`
-- [BC Break] `Parameter::value` to replace `InnerList::parameter` and `Item::parameter`
+- `Parameter::merge` accepts any iterable that can be accepted by `Parameter::fromAssociative` as variadic parameter
+- **[BC Break]** `InnerList::fromList` to replace `InnerList::fromMembers`
+- **[BC Break]** `OrderedList::fromList` to replace `OrderedList::fromMembers`
+- **[BC Break]** `Parameter::value` to replace `InnerList::parameter` and `Item::parameter`
 
 ### Fixed
 
 - `ByteSequence::fromDecoded` named constructor also accepts a `Stringable` object
 - `ByteSequence::fromEncoded` named constructor also accepts a `Stringable` object
-- [BC Break] `OrderedList::__construct` is made private use `OrderedList::from` instead
-- [BC Break] `InnerList::__construct` is made private use `InnerList::fromList` instead
-- [BC Break] `Token::__construct` is made private use `Token::fromString` instead
+- **[BC Break]** `OrderedList::__construct` is made private use `OrderedList::from` instead
+- **[BC Break]** `InnerList::__construct` is made private use `InnerList::fromList` instead
+- **[BC Break]** `Token::__construct` is made private use `Token::fromString` instead
 
 ### Deprecated
 
 - None
 
 ### Removed
 
-- [BC Break] `InnerList::fromMembers` replaced by `InnerList::fromList`
-- [BC Break] `OrderedList::fromMembers` replaced by `OrderedList::fromList`
-- [BC Break] `Item::parameter` replaced by `Parameter::value`
-- [BC Break] `InnerList::parameter` replaced by `Parameter::value`
+- **[BC Break]** `InnerList::fromMembers` replaced by `InnerList::fromList`
+- **[BC Break]** `OrderedList::fromMembers` replaced by `OrderedList::fromList`
+- **[BC Break]** `Item::parameter` replaced by `Parameter::value`
+- **[BC Break]** `InnerList::parameter` replaced by `Parameter::value`
+- **[BC Break]** `SupportsParameters` interface is removed without replacement
+- **[BC Break]** `Item::value()` replaced by `Item::value` public readonly property
+- **[BC Break]** `Item::parameters()` replaced by `Item::parameters` public readonly property
+- **[BC Break]** `InnerList::parameters()` replaced by `InnerList::parameters` public readonly property
 
 ## [0.1.0] - 2022-03-18
 

README.md

@@ -24,9 +24,9 @@ The package can be used to:
 use Bakame\Http\StructuredFields\Item;
 
 $field = Item::from("/terms", ['rel' => "copyright", 'anchor' => '#foo']);
-echo $field->toHttpValue();    //display "/terms";rel="copyright";anchor="#foo"
-echo $field->value();          //display "/terms"
-echo $field->parameter('rel'); //display "copyright"
+echo $field->toHttpValue();           //display "/terms";rel="copyright";anchor="#foo"
+echo $field->value;                   //display "/terms"
+echo $field->parameter->value('rel'); //display "copyright"
 ```
 
 System Requirements
@@ -119,18 +119,17 @@ Instantiation via type recognition is done using the `Item::from` named construc
 use Bakame\Http\StructuredFields\Item;
 
 $item = Item::from("hello world", ["a" => 1]);
-$item->value(); //returns "hello world"
+$item->value; //returns "hello world"
 $item->isString(); //return true
 $item->isToken();  //return false
-$item->parameter("a"); //returns 1
+$item->parameters->value("a"); //returns 1
 ```
 
 
-Once instantiated, accessing `Item` properties is done via three (3) methods:
+Once instantiated, accessing `Item` properties is done via three (2) readonly properties:
 
-- `Item::value()` which returns the instance underlying value
-- `Item::parameters()` which returns the parameters associated to the `Item` as a distinct `Parameters` object
-- `Item::parameter(string $key)` which returns the HTTP data type attached to the parameter `$key`.
+- `Item::value` which returns the instance underlying value
+- `Item::parameters` which returns the parameters associated to the `Item` as a distinct `Parameters` object
 
 **Of note: to instantiate a decimal number type a float MUST be used as the first argument input.**
 
@@ -220,6 +219,7 @@ The `Parameters` instance exposes the following methods:
 
 - `Parameters::values` to list all existing Bare Items value as an array list;
 - `Parameters::value($key)` to return the value of the Bare Item associated to the `$key` or throw if the key is unknown or invalid;
+- `Parameters::merge` also accepts iterable as associative key-value as part of the variadic signature.
 
 ```php
 use Bakame\Http\StructuredFields\Parameters;
@@ -233,6 +233,12 @@ $parameters->value('b'); // returns true
 $parameters->get('b'); // returns Item::from(true)
 iterator_to_array($parameters->toPairs(), true); // returns [['b', Item::from(true)], ['foo', Item::from('bar')]]
 iterator_to_array($parameters, true); // returns ['b' => Item::from(true), 'foo' => Item::from('bar')]
+$parameters->merge(
+    Parameters::fromAssociative(['b' => true, 'foo' => 'foo']),
+    ['b' => 'false']
+);
+$parameters->toHttpValue(); // returns ;b="false";foo="foo"
+
 ```
 
 #### Lists
@@ -277,15 +283,15 @@ RFC but the main ones are:
 
 - `InnerList` members must be `Items`;
 - `OrderedList` members must be `InnerList` or `Items`;
-- `InnerList` can have a `Parameters` instance attached to it, not `OrderedList`;
+- `InnerList` has a `Parameters` instance attached to it that you can access via its readonly property `parameters`, not `OrderedList`;
 
 ```php
 use Bakame\Http\StructuredFields\InnerList;
 use Bakame\Http\StructuredFields\Parameters;
 
 $innerList = InnerList::fromList([42, 42.0, "42"], ["a" => true]);
-$innerList->parameters();   //returns a Parameters object
-$innerList->parameters()->value('a'); // returns true
+$innerList->parameters;             //returns a Parameters object
+$innerList->parameters->value('a'); // returns true
 ```
 
 Contributing

phpstan.neon

@@ -7,4 +7,6 @@ parameters:
     paths:
         - src
     ignoreErrors:
+        - message: '#Method Bakame\\Http\\StructuredFields\\Parameters::merge\(\) has parameter \$others with no value type specified in iterable type iterable.#'
+          path: src/Parameters.php
     reportUnmatchedIgnoredErrors: true

src/Dictionary.php

@@ -85,7 +85,7 @@ public function toHttpValue(): string
         $returnValue = [];
         foreach ($this->members as $key => $member) {
             $returnValue[] = match (true) {
-                $member instanceof Item && true === $member->value() => $key.$member->parameters()->toHttpValue(),
+                $member instanceof Item && true === $member->value => $key.$member->parameters->toHttpValue(),
                 default => $key.'='.$member->toHttpValue(),
             };
         }

src/DictionaryTest.php

@@ -78,8 +78,8 @@ public function it_can_add_or_remove_members(): void
         /** @var array{0:string, 1:Item} $foundItem */
         $foundItem = $instance->pair(1);
 
-        self::assertIsString($foundItem[1]->value());
-        self::assertStringContainsString('BarBaz', $foundItem[1]->value());
+        self::assertIsString($foundItem[1]->value);
+        self::assertStringContainsString('BarBaz', $foundItem[1]->value);
 
         $instance->delete('foobar', 'string');
         self::assertCount(0, $instance);

src/InnerList.php

@@ -16,13 +16,15 @@
 /**
  * @implements IteratorAggregate<array-key, Item>
  */
-final class InnerList implements Countable, IteratorAggregate, StructuredField, SupportsParameters
+final class InnerList implements Countable, IteratorAggregate, StructuredField
 {
     /** @var array<Item> */
     private array $members;
 
-    private function __construct(private Parameters $parameters, Item ...$members)
-    {
+    private function __construct(
+        public readonly Parameters $parameters,
+        Item ...$members
+    ) {
         $this->members = $members;
     }
 
@@ -69,19 +71,6 @@ public function toHttpValue(): string
             .$this->parameters->toHttpValue();
     }
 
-    public function parameters(): Parameters
-    {
-        return $this->parameters;
-    }
-
-    /**
-     * @param Parameters|iterable<array-key, Item|Token|ByteSequence|float|int|bool|string> $parameters
-     */
-    public function exchangeParameters(Parameters|iterable $parameters): void
-    {
-        $this->parameters = Parameters::fromAssociative($parameters);
-    }
-
     public function count(): int
     {
         return count($this->members);
@@ -203,7 +192,7 @@ public function merge(self ...$others): void
     {
         foreach ($others as $other) {
             $this->members = [...$this->members, ...$other->members];
-            $this->parameters->merge($other->parameters());
+            $this->parameters->merge($other->parameters);
         }
     }
 }

src/InnerListTest.php

@@ -22,7 +22,7 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
         $booleanItem = Item::from(true);
         $arrayParams = [$stringItem, $booleanItem];
         $instance = InnerList::fromList($arrayParams, Parameters::fromAssociative(['test' => Item::from(42)]));
-        self::assertFalse($instance->parameters()->isEmpty());
+        self::assertFalse($instance->parameters->isEmpty());
 
         self::assertSame($stringItem, $instance->get(0));
         self::assertFalse($instance->isEmpty());
@@ -44,7 +44,7 @@ public function it_can_add_or_remove_members(): void
 
         self::assertCount(2, $instance);
         self::assertTrue($instance->has(1));
-        self::assertTrue($instance->parameters()->isEmpty());
+        self::assertTrue($instance->parameters->isEmpty());
 
         $instance->remove(1);
 
@@ -55,8 +55,8 @@ public function it_can_add_or_remove_members(): void
         $instance->insert(1, );
         $member = $instance->get(1);
         self::assertCount(2, $instance);
-        self::assertIsString($member->value());
-        self::assertStringContainsString('BarBaz', $member->value());
+        self::assertIsString($member->value);
+        self::assertStringContainsString('BarBaz', $member->value);
 
         $instance->remove(0, 1);
         self::assertCount(0, $instance);
@@ -176,7 +176,7 @@ public function it_can_access_its_parameter_values(): void
     {
         $instance = InnerList::fromList([false], ['foo' => 'bar']);
 
-        self::assertSame('bar', $instance->parameters()->value('foo'));
+        self::assertSame('bar', $instance->parameters->value('foo'));
     }
 
     /**
@@ -187,7 +187,7 @@ public function it_fails_to_access_unknown_parameter_values(): void
         $this->expectException(InvalidOffset::class);
 
         $instance = InnerList::fromList([false], ['foo' => 'bar']);
-        $instance->parameters()->value('bar');
+        $instance->parameters->value('bar');
     }
 
     /**
@@ -197,11 +197,11 @@ public function it_can_exchange_parameters(): void
     {
         $instance = InnerList::from(false, true, 42, 'forty-two');
 
-        self::assertCount(0, $instance->parameters());
+        self::assertCount(0, $instance->parameters);
+        $instance->parameters->clear();
+        $instance->parameters->merge(['foo' => 'bar']);
 
-        $instance->exchangeParameters(['foo' => 'bar']);
-
-        self::assertCount(1, $instance->parameters());
-        self::assertSame('bar', $instance->parameters()->value('foo'));
+        self::assertCount(1, $instance->parameters);
+        self::assertSame('bar', $instance->parameters->value('foo'));
     }
 }

src/Item.php

@@ -18,11 +18,11 @@
 use function substr;
 use function trim;
 
-final class Item implements StructuredField, SupportsParameters
+final class Item implements StructuredField
 {
     private function __construct(
-        private Token|ByteSequence|int|float|string|bool $value,
-        private Parameters $parameters
+        public readonly Token|ByteSequence|int|float|string|bool $value,
+        public readonly Parameters $parameters
     ) {
     }
 
@@ -263,24 +263,6 @@ private function serializeDecimal(float $value): string
         return $result.'.0';
     }
 
-    public function value(): Token|ByteSequence|int|float|string|bool
-    {
-        return $this->value;
-    }
-
-    public function parameters(): Parameters
-    {
-        return $this->parameters;
-    }
-
-    /**
-     * @param Parameters|iterable<array-key, Item|Token|ByteSequence|float|int|bool|string> $parameters
-     */
-    public function exchangeParameters(Parameters|iterable $parameters): void
-    {
-        $this->parameters = Parameters::fromAssociative($parameters);
-    }
-
     public function isInteger(): bool
     {
         return is_int($this->value);

src/ItemTest.php

@@ -97,7 +97,7 @@ public function it_instantiates_a_token(): void
      */
     public function it_instantiates_a_binary(): void
     {
-        self::assertInstanceOf(ByteSequence::class, Item::from(ByteSequence::fromDecoded('foobar'))->value());
+        self::assertInstanceOf(ByteSequence::class, Item::from(ByteSequence::fromDecoded('foobar'))->value);
     }
 
     /**
@@ -228,7 +228,7 @@ public function it_can_access_its_parameter_values(): void
     {
         $instance = Item::fromHttpValue('1; a; b=?0');
 
-        self::assertTrue($instance->parameters()->value('a'));
+        self::assertTrue($instance->parameters->value('a'));
     }
 
     /**
@@ -239,7 +239,7 @@ public function it_fails_to_access_unknown_parameter_values(): void
         $this->expectException(InvalidOffset::class);
 
         $instance = Item::fromHttpValue('1; a; b=?0');
-        $instance->parameters()->value('bar');
+        $instance->parameters->value('bar');
     }
 
     /**
@@ -249,11 +249,12 @@ public function it_can_exchange_parameters(): void
     {
         $instance = Item::from(Token::fromString('babayaga'));
 
-        self::assertCount(0, $instance->parameters());
+        self::assertCount(0, $instance->parameters);
 
-        $instance->exchangeParameters(['foo' => 'bar']);
+        $instance->parameters->clear();
+        $instance->parameters->merge(['foo' => 'bar']);
 
-        self::assertCount(1, $instance->parameters());
-        self::assertSame('bar', $instance->parameters()->value('foo'));
+        self::assertCount(1, $instance->parameters);
+        self::assertSame('bar', $instance->parameters->value('foo'));
     }
 }

src/OrderedListTest.php

@@ -54,8 +54,8 @@ public function it_can_add_or_remove_members(): void
 
         self::assertCount(2, $instance);
         self::assertInstanceOf(Item::class, $member);
-        self::assertIsString($member->value());
-        self::assertStringContainsString('BarBaz', $member->value());
+        self::assertIsString($member->value);
+        self::assertStringContainsString('BarBaz', $member->value);
 
         $instance->remove(0, 1);
         self::assertCount(0, $instance);