Improce ParameterAccess interface

Author: nyamsprod

CHANGELOG.md

@@ -13,6 +13,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - `Token::value` is a readonly property.
 - `Item::value` method returns the decoded value of an Item (returns value can be `float|int|string|bool`).
 - `Item::fromToken`, `Item::fromDecodedByteSequence` , `Item::fromEncodedByteSequence` to ease `Item` creation. 
+- `Item::withValue` to ease `Item` value update.
 - `Parser` methods also accepts `Stringable` objects.
 
 ### Fixed
@@ -35,6 +36,9 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - **[BC Break]** `isEmpty` method is removed use `hasMembers` method instead.
 - **[BC Break]** `Parameters::value` use `Item::value` method instead.
 - **[BC Break]** `Parameters::values` use `Parameters::getIterator` instead.
+- **[BC Break]** `Item::value` public readonly property use `Item::value` method instead.
+- **[BC Break]** `Item::parameters` public readonly property use `Item::parameters` method instead.
+- **[BC Break]** `InnerList::parameters` public readonly property use `InnerList::parameters` method instead.
 
 ## [0.5.0] - 2022-05-13
 

README.md

@@ -25,7 +25,7 @@ use Bakame\Http\StructuredFields;
 $field = StructuredFields\Item::from("/terms", ['rel' => 'copyright', 'anchor' => '#foo']);
 echo $field->toHttpValue();              // display "/terms";rel="copyright";anchor="#foo"
 echo $field->value();                    // display "/terms"
-echo $field->parameters['rel']->value(); // display "copyright"
+echo $field->parameters()['rel']->value(); // display "copyright"
 ```
 
 System Requirements

docs/item.md

@@ -69,7 +69,7 @@ $item = StructuredFields\Item::from("hello world", ["a" => true]);
 $item->value();    // returns "hello world"
 $item->isString(); // returns true
 $item->isToken();  // returns false
-$item->parameters["a"]->value(); //returns true
+$item->parameters()['a']->value(); //returns true
 ```
 
 Instantiation via type recognition is done using the `Item::from` named constructor.
@@ -84,7 +84,7 @@ It is possible to use
 - `Item::fromEncodedByteSequence` internally use `ByteSequence::fromEncoded`
 - `Item::fromDecodedByteSequence` internally use `ByteSequence::fromDecoded`
 
-Those listed named constructores expect a string or a stringable object as its first argument and the
+Those listed named constructors expect a string or a stringable object as its first argument and the
 same argument definition as in `Item::from` for parameters argument.
 
 ```php
@@ -97,8 +97,8 @@ $item = StructuredFields\Item::fromPair([
 ]);
 $item->value();    // returns "hello world"
 $item->isString(); // returns true
-$item->parameters["a"]->isByteSequence(); // returns true
-$item->parameters["a"]->value(); // returns the decoded value 'Hello World'
+$item->parameters()["a"]->isByteSequence(); // returns true
+$item->parameters()["a"]->value(); // returns the decoded value 'Hello World'
 echo $item->toHttpValue();       // returns "hello world";a=:SGVsbG8gV29ybGQ=:
 ```
 
@@ -112,7 +112,7 @@ a tuple composed by an array as a list where:
 Once instantiated, accessing `Item` properties is done via:
 
 - the method `Item::value` which returns the instance underlying value fully decoded;
-- the readonly property `Item::parameters` which returns the parameters associated to the `Item` as a distinct `Parameters` object
+- the method `Item::parameters` which returns the parameters associated to the `Item` as a distinct `Parameters` object
 
 ```php
 use Bakame\Http\StructuredFields;

src/ByteSequence.php

@@ -28,7 +28,7 @@ public static function fromEncoded(Stringable|string $encodedValue): self
 
         $decoded = base64_decode($encodedValue, true);
         if (false === $decoded) {
-            throw new SyntaxError('Invalid character in byte sequence');
+            throw new SyntaxError('Unable to base64 decode the byte sequence');
         }
 
         return new self($decoded);

src/ByteSequenceTest.php

@@ -15,13 +15,21 @@ final class ByteSequenceTest extends StructuredFieldTest
     ];
 
     /** @test */
-    public function it_will_fail_on_invalid_decoded_string(): void
+    public function it_will_fail_on_invalid_decoded_string_with_inner_space(): void
     {
         $this->expectException(SyntaxError::class);
 
         ByteSequence::fromEncoded('a a');
     }
 
+    /** @test */
+    public function it_will_fail_on_invalid_decoded_string(): void
+    {
+        $this->expectException(SyntaxError::class);
+
+        ByteSequence::fromEncoded('aaaaa');
+    }
+
     /** @test */
     public function it_can_decode_base64_field(): void
     {

src/Dictionary.php

@@ -73,16 +73,18 @@ public static function fromPairs(MemberOrderedMap|iterable $pairs = []): self
      */
     public static function fromHttpValue(Stringable|string $httpValue): self
     {
-        return self::fromAssociative(array_map(
-            fn (mixed $value): mixed => is_array($value) ? InnerList::fromList(...$value) : $value,
-            Parser::parseDictionary($httpValue)
-        ));
+        $instance = new self();
+        foreach (Parser::parseDictionary($httpValue) as $key => $value) {
+            $instance->set($key, is_array($value) ? InnerList::fromList(...$value) : $value);
+        }
+
+        return $instance;
     }
 
     public function toHttpValue(): string
     {
         $formatter = fn (Item|InnerList $member, string $key): string => 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(),
         };
 
@@ -149,7 +151,7 @@ public function get(string|int $offset): Item|InnerList
             throw InvalidOffset::dueToKeyNotFound($offset);
         }
 
-        return self::filterForbiddenState($this->members[$offset]);
+        return $this->members[$offset];
     }
 
     /**
@@ -218,31 +220,12 @@ public function set(string $key, StructuredField|ByteSequence|Token|bool|int|flo
     private static function filterMember(StructuredField|ByteSequence|Token|bool|int|float|string $member): InnerList|Item
     {
         return match (true) {
-            $member instanceof InnerList, $member instanceof Item => self::filterForbiddenState($member),
+            $member instanceof InnerList, $member instanceof Item => $member,
             $member instanceof StructuredField => throw new InvalidArgument('Expecting a "'.Item::class.'" or a "'.InnerList::class.'" instance; received a "'.$member::class.'" instead.'),
             default => Item::from($member),
         };
     }
 
-    private static function filterForbiddenState(InnerList|Item $member): InnerList|Item
-    {
-        foreach ($member->parameters as $offset => $item) {
-            if ($item->parameters->hasMembers()) {
-                throw new ForbiddenStateError('Parameter member "'.$offset.'" is in invalid state; Parameters instances can only contain bare items.');
-            }
-        }
-
-        if ($member instanceof Item) {
-            return $member;
-        }
-
-        foreach ($member as $item) {
-            self::filterForbiddenState($item);
-        }
-
-        return $member;
-    }
-
     /**
      * Deletes members associated with the list of submitted keys.
      */

src/DictionaryTest.php

@@ -215,22 +215,6 @@ public function it_can_handle_string_with_comma(): void
         self::assertCount(2, $instance);
     }
 
-    /** @test */
-    public function it_fails_http_conversion_with_invalid_parameters(): void
-    {
-        $this->expectException(StructuredFieldError::class);
-
-        $structuredField = Dictionary::fromPairs();
-        $structuredField->append('item', 42);
-        $item = $structuredField->get('item');
-        $item->parameters->append('forty-two', '42');
-        $wrongUpdatedItem = $item->parameters->get('forty-two');
-        $wrongUpdatedItem->parameters->append('invalid-value', 'not-valid');
-        self::assertCount(1, $wrongUpdatedItem->parameters);
-
-        $structuredField->toHttpValue();
-    }
-
     /** @test */
     public function it_fails_to_add_an_integer_via_array_access(): void
     {
@@ -276,20 +260,4 @@ public function it_can_access_the_item_value(): void
         self::assertInstanceOf(Item::class, $structuredField->get('false'));
         self::assertFalse($structuredField->get('false')->value());
     }
-
-    /** @test */
-    public function it_will_strip_invalid_state_object_via_values_methods(): void
-    {
-        $this->expectException(StructuredFieldError::class);
-        $bar = Item::from(Token::fromString('bar'));
-        $bar->parameters->set('baz', 42);
-        $innerList = InnerList::from('foobar');
-        $structuredField = Dictionary::fromAssociative()
-            ->set('b', false)
-            ->set('a', $bar)
-            ->set('c', $innerList);
-
-        $structuredField->get('a')->parameters['baz']->parameters->set('error', 'error');
-        $structuredField->toHttpValue();
-    }
 }

src/InnerList.php

@@ -46,26 +46,32 @@ public static function fromList(iterable $members = [], iterable $parameters = [
     private static function filterMember(StructuredField|ByteSequence|Token|bool|int|float|string $member): Item
     {
         return match (true) {
-            $member instanceof Item => self::filterForbiddenState($member),
+            $member instanceof Item => $member,
             $member instanceof StructuredField => throw new InvalidArgument('Expecting a "'.Item::class.'" instance; received a "'.$member::class.'" instance instead.'),
             default => Item::from($member),
         };
     }
 
-    private static function filterForbiddenState(Item $member): Item
+    public static function fromHttpValue(Stringable|string $httpValue): self
     {
-        foreach ($member->parameters as $offset => $item) {
-            if ($item->parameters->hasMembers()) {
-                throw new ForbiddenStateError('Parameter member "'.$offset.'" is in invalid state; Parameters instances can only contain bare items.');
-            }
-        }
+        return InnerList::fromList(...Parser::parseInnerList($httpValue));
+    }
 
-        return $member;
+    public function parameters(): Parameters
+    {
+        return clone $this->parameters;
     }
 
-    public static function fromHttpValue(Stringable|string $httpValue): self
+    public function withParameters(Parameters $parameters): static
     {
-        return InnerList::fromList(...Parser::parseInnerList($httpValue));
+        if ($this->parameters->toHttpValue() === $parameters->toHttpValue()) {
+            return $this;
+        }
+
+        $newInstance = new self($parameters);
+        $newInstance->members = $this->members;
+
+        return $newInstance;
     }
 
     public function toHttpValue(): string
@@ -121,7 +127,7 @@ public function get(string|int $offset): Item
             throw InvalidOffset::dueToIndexNotFound($offset);
         }
 
-        return self::filterForbiddenState($this->members[$index]);
+        return $this->members[$index];
     }
 
     /**

src/InnerListTest.php

@@ -130,7 +130,7 @@ public function it_successfully_parse_a_http_field(): void
         self::assertSame('hello)world', $instance->get(0)->value());
         self::assertSame(42, $instance->get(1)->value());
         self::assertSame(42.0, $instance->get(2)->value());
-        self::assertSame('doe', $instance->get(2)->parameters['john']->value());
+        self::assertSame('doe', $instance->get(2)->parameters()['john']->value());
     }
 
     /** @test */
@@ -177,21 +177,6 @@ public function testArrayAccessThrowsInvalidIndex2(): void
         self::assertCount(0, $sequence);
     }
 
-    /** @test */
-    public function it_fails_http_conversion_with_invalid_parameters(): void
-    {
-        $this->expectException(StructuredFieldError::class);
-
-        $structuredField = InnerList::from(69);
-        $item = $structuredField->get(0);
-        $item->parameters->append('forty-two', '42');
-        $wrongUpdatedItem = $item->parameters->get('forty-two');
-        $wrongUpdatedItem->parameters->append('invalid-value', 'not-valid');
-        self::assertCount(1, $wrongUpdatedItem->parameters);
-
-        $structuredField->toHttpValue();
-    }
-
     /** @test */
     public function it_fails_to_fetch_an_value_using_an_integer(): void
     {
@@ -213,14 +198,14 @@ public function it_can_access_the_item_value(): void
     }
 
     /** @test */
-    public function it_will_strip_invalid_state_object_via_values_methods(): void
+    public function it_can_create_via_with_parameters_method_a_new_object(): void
     {
-        $this->expectException(ForbiddenStateError::class);
-        $bar = Item::from(Token::fromString('bar'));
-        $bar->parameters->set('baz', 42);
-        $structuredField = InnerList::from(false, $bar);
-        $structuredField[1]->parameters['baz']->parameters->set('error', 'error');
+        $instance1 = InnerList::fromList([Token::fromString('babayaga'), 'a', true], ['a' => true]);
+        $instance2 = $instance1->withParameters(Parameters::fromAssociative(['a' => true]));
+        $instance3 = $instance1->withParameters(Parameters::fromAssociative(['a' => false]));
 
-        $structuredField->toHttpValue();
+        self::assertSame($instance1, $instance2);
+        self::assertNotSame($instance1->parameters(), $instance3->parameters());
+        self::assertEquals(iterator_to_array($instance1), iterator_to_array($instance3));
     }
 }