Interfaces of different types of collections. May be used to build specific collections.

src/Collection/BaseCollection.php

@@ -27,12 +27,12 @@ abstract class BaseCollection implements CollectionInterface
      *
      * @var array
      */
-    private $elements;
+    private array $elements;
 
     /**
      * Class constructor
      *
-     * @param array $elements (optional) The elements of collection
+     * @param array $elements (optional) Elements of collection
      */
     public function __construct(array $elements = [])
     {
@@ -41,10 +41,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Adds given element (at the end of collection)
-     *
-     * @param mixed $element The element to add
-     * @param mixed $index   (optional) Index / key of the element
+     * {@inheritdoc}
      */
     public function add($element, $index = null): void
     {
@@ -62,11 +59,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Adds given elements (at the end of collection)
-     *
-     * @param array|CollectionInterface $elements   The elements to add
-     * @param bool                      $useIndexes (optional) If is set to true, indexes of given elements will be
-     *                                              used in this collection. Otherwise - not.
+     * {@inheritdoc}
      */
     public function addMultiple($elements, bool $useIndexes = false): void
     {
@@ -87,21 +80,32 @@ abstract class BaseCollection implements CollectionInterface
         }
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function append($element): void
+    {
+        $this->elements[] = $element;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
     public function clear(): void
     {
         $this->elements = [];
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function count(): int
     {
         return count($this->elements);
     }
 
     /**
-     * Returns element with given index
-     *
-     * @param mixed $index Index / key of the element
-     * @return null|mixed
+     * {@inheritdoc}
      */
     public function getByIndex($index)
     {
@@ -109,24 +113,23 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Returns the first element in the collection
-     *
-     * @return mixed
+     * {@inheritdoc}
      */
     public function getFirst()
     {
         return Arrays::getFirstElement($this->elements);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getIterator(): ArrayIterator
     {
         return new ArrayIterator($this->elements);
     }
 
     /**
-     * Returns the last element in the collection
-     *
-     * @return mixed
+     * {@inheritdoc}
      */
     public function getLast()
     {
@@ -134,10 +137,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Returns next element for given element
-     *
-     * @param mixed $element The element to verify
-     * @return null|mixed
+     * {@inheritdoc}
      */
     public function getNext($element)
     {
@@ -145,10 +145,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Returns previous element for given element
-     *
-     * @param mixed $element The element to verify
-     * @return null|mixed
+     * {@inheritdoc}
      */
     public function getPrevious($element)
     {
@@ -156,10 +153,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Returns information if the collection has given element, iow. if given element exists in the collection
-     *
-     * @param mixed $element The element to verify
-     * @return bool
+     * {@inheritdoc}
      */
     public function has($element): bool
     {
@@ -169,9 +163,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Returns information if collection is empty
-     *
-     * @return bool
+     * {@inheritdoc}
      */
     public function isEmpty(): bool
     {
@@ -179,10 +171,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Returns information if given element is first in the collection
-     *
-     * @param mixed $element The element to verify
-     * @return bool
+     * {@inheritdoc}
      */
     public function isFirst($element): bool
     {
@@ -190,17 +179,17 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Returns information if given element is last in the collection
-     *
-     * @param mixed $element The element to verify
-     * @return bool
+     * {@inheritdoc}
      */
     public function isLast($element): bool
     {
         return end($this->elements) === $element;
     }
 
-    public function limit(int $max, int $offset = 0): CollectionInterface
+    /**
+     * {@inheritdoc}
+     */
+    public function limit(int $max, int $offset = 0): self
     {
         $result = clone $this;
 
@@ -230,11 +219,17 @@ abstract class BaseCollection implements CollectionInterface
         return $result;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function offsetExists($offset): bool
     {
         return $this->exists($offset);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function offsetGet($offset)
     {
         if ($this->exists($offset)) {
@@ -244,11 +239,17 @@ abstract class BaseCollection implements CollectionInterface
         return null;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function offsetSet($offset, $value): void
     {
         $this->elements[$offset] = $value;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function offsetUnset($offset): void
     {
         if ($this->exists($offset)) {
@@ -257,9 +258,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Prepends given element (adds given element at the beginning of collection)
-     *
-     * @param mixed $element The element to prepend
+     * {@inheritdoc}
      */
     public function prepend($element): void
     {
@@ -267,9 +266,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Removes given element
-     *
-     * @param mixed $element The element to remove
+     * {@inheritdoc}
      */
     public function remove($element): void
     {
@@ -287,9 +284,7 @@ abstract class BaseCollection implements CollectionInterface
     }
 
     /**
-     * Returns representation of object as array
-     *
-     * @return array
+     * {@inheritdoc}
      */
     public function toArray(): array
     {

src/Contract/Collection/AddableCollectionInterface.php

@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Meritoo\Common\Contract\Collection;
+
+/**
+ * Contract for collection that may add elements
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+interface AddableCollectionInterface
+{
+    /**
+     * Adds given element (at the end of collection)
+     *
+     * @param mixed $element The element to add
+     * @param mixed $index   (optional) Index / key of the element
+     * @return void
+     */
+    public function add($element, $index = null): void;
+
+    /**
+     * Adds given elements (at the end of collection)
+     *
+     * @param array|CollectionInterface $elements   The elements to add
+     * @param bool                      $useIndexes (optional) If is set to true, indexes of given elements will be
+     *                                              used in this collection. Otherwise - not.
+     * @return void
+     */
+    public function addMultiple(array $elements, bool $useIndexes = false): void;
+
+    /**
+     * Appends given element (adds given element at the end of collection)
+     *
+     * @param mixed $element The element to add at the end
+     * @return void
+     */
+    public function append($element): void;
+
+    /**
+     * Prepends given element (adds given element at the beginning of collection)
+     *
+     * @param mixed $element The element to add at the beginning
+     * @return void
+     */
+    public function prepend($element): void;
+}

src/Contract/Collection/ClearableCollectionInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Meritoo\Common\Contract\Collection;
+
+/**
+ * Contract for collection that may be cleared (all its elements may be removed)
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+interface ClearableCollectionInterface
+{
+    /**
+     * Removes all elements of the collection
+     *
+     * @return void
+     */
+    public function clear(): void;
+}

src/Contract/Collection/CollectionInterface.php

@@ -11,46 +11,22 @@ declare(strict_types=1);
 namespace Meritoo\Common\Contract\Collection;
 
 use ArrayAccess;
-use Countable;
 use IteratorAggregate;
 
 /**
- * Interface/Contract of collection of elements with the same type
+ * Contract for collection of elements with the same type
  *
  * @author    Meritoo <github@meritoo.pl>
  * @copyright Meritoo <http://www.meritoo.pl>
  */
-interface CollectionInterface extends Countable, ArrayAccess, IteratorAggregate
+interface CollectionInterface extends ArrayAccess, IteratorAggregate, AddableCollectionInterface,
+    RemovableCollectionInterface, CountableCollectionInterface, ClearableCollectionInterface,
+    GettableCollectionInterface, VerifiableCollectionInterface, ReducibleCollectionInterface
 {
-    public function add($element, $index = null): void;
-
-    public function addMultiple($elements, bool $useIndexes = false): void;
-
-    public function clear(): void;
-
-    public function getByIndex($index);
-
-    public function getFirst();
-
-    public function getLast();
-
-    public function getNext($element);
-
-    public function getPrevious($element);
-
-    public function has($element): bool;
-
-    public function isEmpty(): bool;
-
-    public function isFirst($element): bool;
-
-    public function isLast($element): bool;
-
-    public function limit(int $max, int $offset = 0): self;
-
-    public function prepend($element): void;
-
-    public function remove($element): void;
-
+    /**
+     * Returns representation of object as array
+     *
+     * @return array
+     */
     public function toArray(): array;
 }

src/Contract/Collection/CountableCollectionInterface.php

@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Meritoo\Common\Contract\Collection;
+
+use Countable;
+
+/**
+ * Contract for collection that may count its elements
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+interface CountableCollectionInterface extends Countable
+{
+}

src/Contract/Collection/GettableCollectionInterface.php

@@ -0,0 +1,58 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Meritoo\Common\Contract\Collection;
+
+/**
+ * Contract for collection that returns first, last element etc.
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+interface GettableCollectionInterface
+{
+    /**
+     * Returns element with given index
+     *
+     * @param mixed $index Index / key of element to return
+     * @return mixed
+     */
+    public function getByIndex($index);
+
+    /**
+     * Returns first element
+     *
+     * @return mixed
+     */
+    public function getFirst();
+
+    /**
+     * Returns last element
+     *
+     * @return mixed
+     */
+    public function getLast();
+
+    /**
+     * Returns element next after given element
+     *
+     * @param mixed $element The element whose next element should be returned
+     * @return mixed
+     */
+    public function getNext($element);
+
+    /**
+     * Returns element preceding given element
+     *
+     * @param mixed $element The element whose previous element should be returned
+     * @return mixed
+     */
+    public function getPrevious($element);
+}

src/Contract/Collection/ReducibleCollectionInterface.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Meritoo\Common\Contract\Collection;
+
+/**
+ * Contract for collection that may reduce its elements
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+interface ReducibleCollectionInterface
+{
+    /**
+     * Returns new instance of this collection with limited elements
+     *
+     * @param int $max    Maximum elements to return
+     * @param int $offset (optional) Position of element from which limitation should start
+     * @return $this
+     */
+    public function limit(int $max, int $offset = 0): self;
+}

src/Contract/Collection/RemovableCollectionInterface.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Meritoo\Common\Contract\Collection;
+
+/**
+ * Contract for collection that may remove elements
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+interface RemovableCollectionInterface
+{
+    /**
+     * Removes given element
+     *
+     * @param mixed $element The element to remove
+     * @return void
+     */
+    public function remove($element): void;
+}

src/Contract/Collection/VerifiableCollectionInterface.php

@@ -0,0 +1,51 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Meritoo\Common\Contract\Collection;
+
+/**
+ * Contract for collection that may verify its elements
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+interface VerifiableCollectionInterface
+{
+    /**
+     * Returns information if given element exists in collection
+     *
+     * @param mixed $element The element to verify
+     * @return bool
+     */
+    public function has($element): bool;
+
+    /**
+     * Returns information if collection is empty (has not any element)
+     *
+     * @return bool
+     */
+    public function isEmpty(): bool;
+
+    /**
+     * Returns information if given element is the first element in collection
+     *
+     * @param mixed $element The element to verify
+     * @return bool
+     */
+    public function isFirst($element): bool;
+
+    /**
+     * Returns information if given element is the last element in collection
+     *
+     * @param mixed $element The element to verify
+     * @return bool
+     */
+    public function isLast($element): bool;
+}

tests/Collection/BaseCollectionTest.php

@@ -721,6 +721,21 @@ class BaseCollectionTest extends BaseTestCase
         static::assertSame(5, $this->simpleCollection->count());
     }
 
+    public function testAppend(): void
+    {
+        $this->emptyCollection->append('lorem-ipsum');
+
+        static::assertFalse($this->emptyCollection->isEmpty());
+        static::assertSame(1, $this->emptyCollection->count());
+        static::assertSame('lorem-ipsum', $this->emptyCollection[0]);
+
+        $this->simpleCollection->append('lorem-ipsum');
+
+        static::assertFalse($this->simpleCollection->isEmpty());
+        static::assertSame(8, $this->simpleCollection->count());
+        static::assertSame('lorem-ipsum', $this->simpleCollection[347]);
+    }
+
     public function testPrepend()
     {
         $this->emptyCollection->prepend('lorem-ipsum');