Splitsed with() into separate methods to add an item with or without a specific key.

Author: bertramakers

src/AbstractCollection.php

@@ -20,18 +20,24 @@ public function __construct()
     /**
      * @inheritdoc
      */
-    public function with($item, $key = null)
+    public function with($item)
     {
         $this->guardObjectType($item);
 
         $copy = clone $this;
+        $copy->items[] = $item;
+        return $copy;
+    }
 
-        if (is_null($key)) {
-            $copy->items[] = $item;
-        } else {
-            $copy->items[$key] = $item;
-        }
+    /**
+     * @inheritdoc
+     */
+    public function withKey($key, $item)
+    {
+        $this->guardObjectType($item);
 
+        $copy = clone $this;
+        $copy->items[$key] = $item;
         return $copy;
     }
 

src/CollectionInterface.php

@@ -10,17 +10,29 @@ interface CollectionInterface extends \IteratorAggregate
     /**
      * @param mixed $item
      *   Item to add to the Collection.
-     * @param string|null $key
+     *
+     * @return static
+     *   Copy of the Collection, with the new item.
+     *
+     * @throws \InvalidArgumentException
+     *   When the provided item is of an incorrect type.
+     */
+    public function with($item);
+
+    /**
+     * @param string $key
      *   Key to use for the new item. If not provided, the item will be added
      *   to the end of the Collection.
+     * @param mixed $item
+     *   Item to add to the Collection.
      *
      * @return static
      *   Copy of the Collection, with the new item.
      *
      * @throws \InvalidArgumentException
      *   When the provided item is of an incorrect type.
      */
-    public function with($item, $key = null);
+    public function withKey($key, $item);
 
     /**
      * @param mixed $item

tests/CollectionTest.php

@@ -46,8 +46,8 @@ public function setUp()
     public function it_can_create_a_copy_with_a_new_item_for_a_specific_key()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1')
-            ->with($this->foo2, 'foo2');
+            ->withKey('foo1', $this->foo1)
+            ->withKey('foo2', $this->foo2);
 
         $expected = [
             'foo1' => $this->foo1,
@@ -110,7 +110,7 @@ public function it_guards_the_object_type_of_items_when_initializing_from_array(
     public function it_allows_sub_classes_when_guarding_the_object_type_of_new_items()
     {
         $collection = (new FooCollection())
-            ->with($this->fooExtended, 'fooExtended');
+            ->withKey('fooExtended', $this->fooExtended);
 
         $expected = [
             'fooExtended' => $this->fooExtended,
@@ -143,7 +143,7 @@ public function it_can_remove_an_item()
     public function it_throws_an_exception_when_removing_an_unknown_item()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1');
+            ->withKey('foo1', $this->foo1);
 
         $this->setExpectedException(CollectionItemNotFoundException::class);
         $collection->without($this->foo2);
@@ -155,8 +155,8 @@ public function it_throws_an_exception_when_removing_an_unknown_item()
     public function it_can_remove_an_item_by_key()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1')
-            ->with($this->foo2, 'foo2');
+            ->withKey('foo1', $this->foo1)
+            ->withKey('foo2', $this->foo2);
 
         $collection = $collection->withoutKey('foo1');
 
@@ -173,8 +173,8 @@ public function it_can_remove_an_item_by_key()
     public function it_throws_an_exception_when_removing_by_unknown_key()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1')
-            ->with($this->foo2, 'foo2');
+            ->withKey('foo1', $this->foo1)
+            ->withKey('foo2', $this->foo2);
 
         $this->setExpectedException(CollectionKeyNotFoundException::class);
         $collection->withoutKey('foo3');
@@ -186,8 +186,8 @@ public function it_throws_an_exception_when_removing_by_unknown_key()
     public function it_can_return_an_item_by_key()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1')
-            ->with($this->foo2, 'foo2');
+            ->withKey('foo1', $this->foo1)
+            ->withKey('foo2', $this->foo2);
 
         $this->assertEquals(
             $this->foo1,
@@ -206,7 +206,7 @@ public function it_can_return_an_item_by_key()
     public function it_throws_an_exception_when_looking_for_an_item_with_an_unknown_key()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1');
+            ->withKey('foo1', $this->foo1);
 
         $this->setExpectedException(CollectionKeyNotFoundException::class);
         $collection->getByKey('foo2');
@@ -218,8 +218,8 @@ public function it_throws_an_exception_when_looking_for_an_item_with_an_unknown_
     public function it_can_return_the_key_for_an_item()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1')
-            ->with($this->foo2, 'foo2');
+            ->withKey('foo1', $this->foo1)
+            ->withKey('foo2', $this->foo2);
 
         $this->assertEquals(
             'foo1',
@@ -238,7 +238,7 @@ public function it_can_return_the_key_for_an_item()
     public function it_throws_an_exception_when_looking_for_the_key_of_an_unknown_item()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1');
+            ->withKey('foo1', $this->foo1);
 
         $this->setExpectedException(CollectionItemNotFoundException::class);
         $collection->getKeyFor($this->foo2);
@@ -250,8 +250,8 @@ public function it_throws_an_exception_when_looking_for_the_key_of_an_unknown_it
     public function it_can_return_a_list_of_keys()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1')
-            ->with($this->foo2, 'foo2');
+            ->withKey('foo1', $this->foo1)
+            ->withKey('foo2', $this->foo2);
 
         $expected = [
             'foo1',
@@ -297,9 +297,9 @@ public function it_can_be_converted_from_and_to_an_array()
     public function it_can_be_looped_over_like_an_array()
     {
         $collection = (new FooCollection())
-            ->with($this->foo1, 'foo1')
-            ->with($this->foo2, 'foo2')
-            ->with($this->fooExtended, 'fooExtended');
+            ->withKey('foo1', $this->foo1)
+            ->withKey('foo2', $this->foo2)
+            ->withKey('fooExtended', $this->fooExtended);
 
         $expected = [
             'foo1' => $this->foo1,