#3 implementing ArrayAccess for list containers

Author: nyamsprod

CHANGELOG.md

@@ -9,6 +9,7 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 - `Item::fromPair` named constructor to create a new instance from a pair expressed as an array list with two values.
 - `Parameters::sanitize` ensure the container always contains only Bare Items.
 - `autoload.php` script to allow non composer application to load the package
+- `OrderedList` and `InnerList` now implements the PHP `ArrayAccess` interface.
 
 ### Fixed
 

README.md

@@ -367,6 +367,32 @@ setter methods
 - `replace` to replace an element at a given position in the list;
 - `remove` to remove elements based on their position;
 
+Additionally, both classes implements PHP `ArrayAccess` interface as syntactic sugar methods
+around the `get`, `has`, `push`, `remove` and `replace` methods. 
+
+```php
+use Bakame\Http\StructuredFields;
+
+$innerList = StructuredFields\InnerList::fromList([42, 42.0, "42"], ["a" => true]);
+isset($innerList[2]); //return true
+isset($innerList[42]); //return false
+$innerList[] = StructuredFields\Token::fromString('forty-two');
+unset($innerList[0]);
+unset($innerList[1]); //<-- we use `1` instead of 2 because of re-indexation !!!
+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 your logic**
+
+```php
+use Bakame\Http\StructuredFields;
+
+$innerList = StructuredFields\OrderedList::fromList([42, 42.0, "42"], ["a" => true]);
+$innerList[2] = StructuredFields\Token::fromString('forty-two'); // will throw
+```
+
 A `Parameters` instance can be associated to an `InnerList` using the same API as for the `Item` value object.
 
 ```php

src/InnerList.php

@@ -4,6 +4,7 @@
 
 namespace Bakame\Http\StructuredFields;
 
+use ArrayAccess;
 use Countable;
 use Iterator;
 use IteratorAggregate;
@@ -14,9 +15,10 @@
 use function count;
 
 /**
- * @implements IteratorAggregate<array-key, Item>
+ * @implements IteratorAggregate<int, Item>
+ * @implements ArrayAccess<int, Item>
  */
-final class InnerList implements Countable, IteratorAggregate, StructuredField
+final class InnerList implements ArrayAccess, Countable, IteratorAggregate, StructuredField
 {
     /** @var array<Item> */
     private array $members;
@@ -201,4 +203,56 @@ public function clear(): self
 
         return $this;
     }
+
+    /**
+     * @param int $offset the integer index of the member to validate.
+     *
+     * @see ::has
+     */
+    public function offsetExists($offset): bool
+    {
+        return $this->has($offset);
+    }
+
+    /**
+     *
+     * @param int $offset the integer index of the member to retrieve.
+     *
+     * @see ::get
+     */
+    public function offsetGet($offset): Item
+    {
+        return $this->get($offset);
+    }
+
+    /**
+     *
+     * @param int $offset the integer index of the member to remove
+     *
+     * @see ::remove
+     *
+     */
+    public function offsetUnset($offset): void
+    {
+        $this->remove($offset);
+    }
+
+    /**
+     *
+     * @param int|null                                      $offset the integer index of member to add or update
+     * @param Item|ByteSequence|Token|bool|int|float|string $value  the member to add
+     *
+     * @see ::push
+     * @see ::insert
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (null !== $offset) {
+            $this->replace($offset, $value);
+
+            return;
+        }
+
+        $this->push($value);
+    }
 }

src/InnerListTest.php

@@ -173,4 +173,45 @@ public function it_successfully_parse_a_http_field_with_optional_white_spaces_in
             InnerList::fromHttpValue('        ("hello)world" 42 42.0;john=doe);foo="bar("')
         );
     }
+
+    /**
+     * @test
+     */
+    public function it_implements_the_array_access_interface(): void
+    {
+        $sequence = InnerList::fromList();
+        $sequence[] = 42;
+
+        self::assertTrue(isset($sequence[0]));
+        self::assertEquals(42, $sequence[0]->value);
+
+        $sequence[0] = false;
+
+        self::assertNotEquals(42, $sequence[0]->value);
+        unset($sequence[0]);
+
+        self::assertCount(0, $sequence);
+    }
+
+    /**
+     * @test
+     */
+    public function it_fails_to_insert_unknown_index_via_the_array_access_interface(): void
+    {
+        $this->expectException(StructuredFieldError::class);
+
+        $sequence = InnerList::fromList();
+        $sequence[0] = Item::from(42.0);
+    }
+
+    /**
+     * @test
+     */
+    public function testArrayAccessThrowsInvalidIndex2(): void
+    {
+        $sequence = InnerList::from();
+        unset($sequence[0]);
+
+        self::assertCount(0, $sequence);
+    }
 }

src/OrderedList.php

@@ -4,6 +4,7 @@
 
 namespace Bakame\Http\StructuredFields;
 
+use ArrayAccess;
 use Countable;
 use Iterator;
 use IteratorAggregate;
@@ -16,8 +17,9 @@
 
 /**
  * @implements IteratorAggregate<array-key, Item|InnerList>
+ * @implements ArrayAccess<int, Item|InnerList>
  */
-final class OrderedList implements Countable, IteratorAggregate, StructuredField
+final class OrderedList implements ArrayAccess, Countable, IteratorAggregate, StructuredField
 {
     /** @var array<Item|InnerList>  */
     private array $members;
@@ -211,4 +213,56 @@ public function clear(): self
 
         return $this;
     }
+
+    /**
+     * @param int $offset the integer index of the member to validate.
+     *
+     * @see ::has
+     */
+    public function offsetExists($offset): bool
+    {
+        return $this->has($offset);
+    }
+
+    /**
+     *
+     * @param int $offset the integer index of the member to retrieve.
+     *
+     * @see ::get
+     */
+    public function offsetGet($offset): Item|InnerList
+    {
+        return $this->get($offset);
+    }
+
+    /**
+     *
+     * @param int $offset the integer index of the member to remove
+     *
+     * @see ::remove
+     *
+     */
+    public function offsetUnset($offset): void
+    {
+        $this->remove($offset);
+    }
+
+    /**
+     *
+     * @param int|null                                                $offset the integer index of member to add or update
+     * @param InnerList|Item|ByteSequence|Token|bool|int|float|string $value  the member to add
+     *
+     * @see ::push
+     * @see ::insert
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (null !== $offset) {
+            $this->replace($offset, $value);
+
+            return;
+        }
+
+        $this->push($value);
+    }
 }

src/OrderedListTest.php

@@ -144,4 +144,46 @@ public function test_it_can_generate_the_same_value(): void
 
         self::assertSame($res->toHttpValue(), $list->toHttpValue());
     }
+
+    /**
+     * @test
+     */
+    public function it_implements_the_array_access_interface(): void
+    {
+        $sequence = OrderedList::fromList();
+        $sequence[] = InnerList::from(42, 69);
+
+        self::assertTrue(isset($sequence[0]));
+        self::assertInstanceOf(InnerList::class, $sequence[0]);
+        self::assertEquals(42, $sequence[0]->get(0)->value);
+
+        $sequence[0] = false;
+
+        self::assertEquals(Item::from(false), $sequence[0]);
+        unset($sequence[0]);
+
+        self::assertFalse(isset($sequence[0]));
+    }
+
+    /**
+     * @test
+     */
+    public function it_fails_to_insert_unknown_index_via_the_array_access_interface(): void
+    {
+        $this->expectException(StructuredFieldError::class);
+
+        $sequence = OrderedList::fromList();
+        $sequence[0] = Item::from(42.0);
+    }
+
+    /**
+     * @test
+     */
+    public function testArrayAccessThrowsInvalidIndex2(): void
+    {
+        $sequence = OrderedList::from();
+        unset($sequence[0]);
+
+        self::assertCount(0, $sequence);
+    }
 }