Convert package to use immutable value objects

Author: nyamsprod

CHANGELOG.md

@@ -15,6 +15,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - `Dictionnary::create` named constructor to create a new instance without any parameter.
 - `Type` Enum to list all possible Item Type supported.
 - `Value` Interface is introduced with `Item` being the only available implementation.
+- `MemberOrderedMap::add` and `MemberOrderedMap::remove` methods
 
 ### Fixed
 
@@ -23,6 +24,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - **[BC Break]** `::fromAssociative`, `::fromList`, `::fromPairs` methods require iterable arguments without default value.
 - **[BC Break]** `Item::value` method returns the Item (returns value can be `float|int|string|bool|ByteSequence|DateTimeImmutable|Token`).
 - **[BC Break]** `InnerList::parameters` is no longer accessible as a public readonly property.
+- **[BC Break]** Modifying container instances with `ArrayAccess` modifying methods is forbidden and will trigger a `LogicException` exception.
 
 ### Deprecated
 
@@ -32,6 +34,8 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 - **[BC Break]** `ForbiddenStateError` exception is removed, the `InvalidArgument` exception is used instead.
 - **[BC Break]** `Item::is*` methods are removed, the enum `Type` is used instead.
+- **[BC Break]**  `MemberContainer::clear` method is removed without replacement.
+- **[BC Break]** - `MemberOrderedMap::set` and `MemberOrderedMap::delete` methods; use `MemberOrderedMap::add` and `MemberOrderedMap::remove` instead
 
 ## [0.6.0] - 2022-11-12
 

docs/containers.md

@@ -26,9 +26,8 @@ At any given time it is possible with each of these objects to:
 
 - iterate over its members using the `IteratorAggregate` interface;
 - know the number of members it contains via the `Countable` interface;
-- access container members via the `ArrayAccess` interface;
 - tell whether the container contains or not members with the `hasMembers` methods from the `Container` interface;
-- clear its content using the `clear` method from the `Container` interface;
+- to access the members using the methods exposed by the `ArrayAccess`. **WARNING: Updating using `ArrayAccess` method is forbidden and will result in a `LogicException` being emitted.**;
 
 getter methods:
 
@@ -37,5 +36,5 @@ getter methods:
 
 **Of note:**
 
-- All setter methods are chainable
+- All setter methods are returns a new instance with the applied changes.
 - For setter methods, Item types are inferred using `Item::from` if a `Item` object is not provided.

docs/index.md

@@ -23,9 +23,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->parameters['rel']->value(); // display "copyright"
+echo $field->toHttpValue();                   // display "/terms";rel="copyright";anchor="#foo"
+echo $field->value();                         // display "/terms"
+echo $field->parameters->get('rel')->value(); // display "copyright"
 ```
 
 System Requirements
@@ -53,7 +53,7 @@ require 'path/to/http-structured-fields/repo/autoload.php';
 use Bakame\Http\StructuredFields\OrderedList;
 
 $list = OrderedList::fromHttpValue('"/member/*/author", "/member/*/comments"');
-echo $list[-1]->value(); // returns '/member/*/comments'
+echo $list->get(-1)->value(); // returns '/member/*/comments'
 ~~~
 
 Documentation

docs/lists.md

@@ -53,20 +53,6 @@ $orderedList = OrderedList::from(
 echo $orderedList->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
 ```
 
-Same example using the `ArrayAccess` interface.
-
-```php
-use Bakame\Http\StructuredFields\InnerList;
-use Bakame\Http\StructuredFields\Token;
-
-$innerList = InnerList::fromList([42, 42.0, "42"], ["a" => true]);
-isset($innerList[2]); //return true
-isset($innerList[42]); //return false
-$innerList[] = Token::fromString('forty-two');
-unset($innerList[0], $innerList[2]);
-echo $innerList->toHttpValue(); //returns '(42.0 forty-two);a'
-```
-
 **if you try to set a key which does not exist an exception will be
 thrown as both classes must remain valid lists with no empty
 keys. Be aware that re-indexation behaviour may affect
@@ -77,6 +63,6 @@ use Bakame\Http\StructuredFields\OrderedList;
 use Bakame\Http\StructuredFields\Token;
 
 $innerList = OrderedList::fromList([42, 42.0]);
-$innerList[2] = Token::fromString('forty-two'); // will throw
+$innerList->insert(2, Token::fromString('forty-two')); // will throw
 echo $innerList->toHttpValue(), PHP_EOL;
 ```

docs/ordered-maps.md

@@ -26,10 +26,10 @@ getter methods:
 
 setter methods:
 
-- `set` add an element at the end of the container if the key is new otherwise only the value is updated;
+- `add` add an element at the end of the container if the key is new otherwise only the value is updated;
 - `append` always add an element at the end of the container, if already present the previous value is removed;
 - `prepend` always add an element at the beginning of the container, if already present the previous value is removed;
-- `delete` to remove elements based on their associated keys;
+- `remove` to remove elements based on their associated keys;
 - `mergeAssociative` merge multiple instances of iterable structure as associative constructs;
 - `mergePairs` merge multiple instances of iterable structure as pairs constructs;
 
@@ -53,24 +53,22 @@ $dictionary->hasPair(-1); //return true
 
 echo $dictionary
     ->append('z', 42.0)
-    ->delete('b', 'c')
+    ->remove('b', 'c')
     ->toHttpValue(); // returns "a=?0, z=42.0"
 ```
 
 In addition to `StructuredField` specific interfaces, both classes implements:
 
 - PHP `Countable` interface.
 - PHP `IteratorAggregate` interface.
-- PHP `ArrayAccess` interface.
 
 ```php
 use Bakame\Http\StructuredFields\Parameters;
 
 $parameters = Parameters::fromAssociative(['b' => true, 'foo' => 'bar']);
-$parameters->keys();       // returns ['b', 'foo']
-$parameters->get('b');     // returns Item::from(true)
-$parameters['b'];          // returns Item::from(true)
-$parameters['b']->value(); // returns true
+$parameters->keys();            // returns ['b', 'foo']
+$parameters->get('b');          // returns Item::from(true)
+$parameters->get('b')->value(); // returns 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->mergeAssociative(

src/ByteSequence.php

@@ -9,6 +9,9 @@
 use function base64_encode;
 use function preg_match;
 
+/**
+ * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.5
+ */
 final class ByteSequence
 {
     private function __construct(

src/Dictionary.php

@@ -4,8 +4,10 @@
 
 namespace Bakame\Http\StructuredFields;
 
+use ArrayAccess;
 use DateTimeInterface;
 use Iterator;
+use LogicException;
 use Stringable;
 use function array_key_exists;
 use function array_keys;
@@ -15,24 +17,39 @@
 use function is_array;
 
 /**
+ * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.2
+ *
  * @implements MemberOrderedMap<string, Value|InnerList<int, Value>>
+ * @implements ArrayAccess<string, Value|InnerList<int, Value>>
  * @phpstan-import-type DataType from Item
  */
-final class Dictionary implements MemberOrderedMap
+final class Dictionary implements MemberOrderedMap, ArrayAccess
 {
     /** @var array<string, Value|InnerList<int, Value>> */
     private array $members = [];
 
     /**
-     * @param iterable<string, InnerList<int, Value>|Value|DataType> $members
+     * @param iterable<string, InnerList<int, Value>|iterable<Value|DataType>|Value|DataType> $members
      */
     private function __construct(iterable $members = [])
     {
         foreach ($members as $key => $member) {
-            $this->set($key, $member);
+            $this->members[MapKey::fromString($key)->value] = self::filterMember($member);
         }
     }
 
+    /**
+     * @param StructuredField|iterable<Value|DataType>|DataType $member
+     */
+    private static function filterMember(iterable|StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): InnerList|Value
+    {
+        return match (true) {
+            $member instanceof InnerList, $member instanceof Value => $member,
+            is_iterable($member) => InnerList::fromList($member),
+            default => Item::from($member),
+        };
+    }
+
     /**
      * Returns a new instance.
      */
@@ -47,7 +64,7 @@ public static function create(): self
      * its keys represent the dictionary entry key
      * its values represent the dictionary entry value
      *
-     * @param iterable<string, InnerList<int, Value>|Value|DataType> $members
+     * @param iterable<string, InnerList<int, Value>|list<Value|DataType>|Value|DataType> $members
      */
     public static function fromAssociative(iterable $members): self
     {
@@ -61,20 +78,19 @@ public static function fromAssociative(iterable $members): self
      * the first member represents the instance entry key
      * the second member represents the instance entry value
      *
-     * @param MemberOrderedMap<string, Value|InnerList<int, Value>>|iterable<array{0:string, 1:InnerList<int, Value>|Value|DataType}> $pairs
+     * @param MemberOrderedMap<string, Value|InnerList<int, Value>>|iterable<array{0:string, 1:InnerList<int, Value>|list<Value|DataType>|Value|DataType}> $pairs
      */
-    public static function fromPairs(MemberOrderedMap|iterable $pairs): self
+    public static function fromPairs(iterable $pairs): self
     {
         if ($pairs instanceof MemberOrderedMap) {
             $pairs = $pairs->toPairs();
         }
 
-        $instance = new self();
-        foreach ($pairs as $pair) {
-            $instance->set(...$pair);
-        }
-
-        return $instance;
+        return new self((function (iterable $pairs) {
+            foreach ($pairs as [$key, $member]) {
+                yield $key => $member;
+            }
+        })($pairs));
     }
 
     /**
@@ -84,12 +100,11 @@ public static function fromPairs(MemberOrderedMap|iterable $pairs): self
      */
     public static function fromHttpValue(Stringable|string $httpValue): self
     {
-        $instance = new self();
-        foreach (Parser::parseDictionary($httpValue) as $key => $value) {
-            $instance->set($key, is_array($value) ? InnerList::fromList(...$value) : $value);
-        }
-
-        return $instance;
+        return new self((function (iterable $pairs) {
+            foreach ($pairs as $key => $value) {
+                yield $key => is_array($value) ? InnerList::fromList(...$value) : $value;
+            }
+        })(Parser::parseDictionary($httpValue)));
     }
 
     public function toHttpValue(): string
@@ -206,79 +221,64 @@ public function pair(int $index): array
         // @codeCoverageIgnoreEnd
     }
 
-    /**
-     * @throws SyntaxError If the string key is not a valid
-     */
-    public function set(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): static
+    public function add(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): static
     {
-        $this->members[MapKey::fromString($key)->value] = self::filterMember($member);
+        $members = $this->members;
+        $members[MapKey::fromString($key)->value] = self::filterMember($member);
 
-        return $this;
-    }
-
-    private static function filterMember(StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): InnerList|Value
-    {
-        return match (true) {
-            $member instanceof InnerList, $member instanceof Value => $member,
-            $member instanceof StructuredField => throw new InvalidArgument('Expecting a "'.Value::class.'" or a "'.InnerList::class.'" instance; received a "'.$member::class.'" instead.'),
-            default => Item::from($member),
-        };
+        return new self($members);
     }
 
-    public function delete(string ...$keys): static
+    public function remove(string ...$keys): static
     {
+        $members = $this->members;
         foreach ($keys as $key) {
-            unset($this->members[$key]);
+            unset($members[$key]);
         }
 
-        return $this;
-    }
-
-    public function clear(): static
-    {
-        $this->members = [];
-
-        return $this;
+        return new self($members);
     }
 
     public function append(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): static
     {
-        unset($this->members[$key]);
+        $members = $this->members;
+        unset($members[$key]);
 
-        return $this->set($key, $member);
+        return new self([...$members, $key => self::filterMember($member)]);
     }
 
     public function prepend(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): static
     {
-        unset($this->members[$key]);
+        $members = $this->members;
+        unset($members[$key]);
 
-        $this->members = [...[MapKey::fromString($key)->value => self::filterMember($member)], ...$this->members];
-
-        return $this;
+        return new self([$key => self::filterMember($member), ...$members]);
     }
 
     /**
      * @param iterable<string, InnerList<int, Value>|Value|DataType> ...$others
      */
     public function mergeAssociative(iterable ...$others): static
     {
+        $members = $this->members;
         foreach ($others as $other) {
-            $this->members = [...$this->members, ...self::fromAssociative($other)->members];
+            $members = [...$members, ...self::fromAssociative($other)->members];
         }
 
-        return $this;
+        return new self($members);
     }
 
     /**
      * @param MemberOrderedMap<string, Value|InnerList<int, Value>>|iterable<array{0:string, 1:InnerList<int, Value>|Value|DataType}> ...$others
      */
     public function mergePairs(MemberOrderedMap|iterable ...$others): static
     {
+        $members = $this->members;
         foreach ($others as $other) {
-            $this->members = [...$this->members, ...self::fromPairs($other)->members];
+            $members = [...$members, ...self::fromPairs($other)->members];
         }
 
-        return $this;
+        return new self($members);
     }
 
     /**
@@ -299,23 +299,13 @@ public function offsetGet(mixed $offset): InnerList|Value
         return $this->get($offset);
     }
 
-    /**
-     * @param string $offset
-     */
     public function offsetUnset(mixed $offset): void
     {
-        $this->delete($offset);
+        throw new LogicException(self::class.' instance can not be updated using '.ArrayAccess::class.' methods.');
     }
 
-    /**
-     * @param InnerList<int, Value>|Value|DataType $value
-     */
     public function offsetSet(mixed $offset, mixed $value): void
     {
-        if (!is_string($offset)) {
-            throw new SyntaxError('The offset for a dictionary member is expected to be a string; "'.gettype($offset).'" given.');
-        }
-
-        $this->set($offset, $value);
+        throw new LogicException(self::class.' instance can not be updated using '.ArrayAccess::class.' methods.');
     }
 }