diff --git a/src/Collection/BaseCollection.php b/src/Collection/BaseCollection.php index f97c4fc..f6ff521 100644 --- a/src/Collection/BaseCollection.php +++ b/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 { diff --git a/src/Contract/Collection/AddableCollectionInterface.php b/src/Contract/Collection/AddableCollectionInterface.php new file mode 100644 index 0000000..e3e30cb --- /dev/null +++ b/src/Contract/Collection/AddableCollectionInterface.php @@ -0,0 +1,55 @@ + + * @copyright Meritoo + */ +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; +} diff --git a/src/Contract/Collection/ClearableCollectionInterface.php b/src/Contract/Collection/ClearableCollectionInterface.php new file mode 100644 index 0000000..96b6186 --- /dev/null +++ b/src/Contract/Collection/ClearableCollectionInterface.php @@ -0,0 +1,27 @@ + + * @copyright Meritoo + */ +interface ClearableCollectionInterface +{ + /** + * Removes all elements of the collection + * + * @return void + */ + public function clear(): void; +} diff --git a/src/Contract/Collection/CollectionInterface.php b/src/Contract/Collection/CollectionInterface.php index 855a01c..e97ec1e 100644 --- a/src/Contract/Collection/CollectionInterface.php +++ b/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 * @copyright Meritoo */ -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; } diff --git a/src/Contract/Collection/CountableCollectionInterface.php b/src/Contract/Collection/CountableCollectionInterface.php new file mode 100644 index 0000000..063cf07 --- /dev/null +++ b/src/Contract/Collection/CountableCollectionInterface.php @@ -0,0 +1,23 @@ + + * @copyright Meritoo + */ +interface CountableCollectionInterface extends Countable +{ +} diff --git a/src/Contract/Collection/GettableCollectionInterface.php b/src/Contract/Collection/GettableCollectionInterface.php new file mode 100644 index 0000000..5b2ca54 --- /dev/null +++ b/src/Contract/Collection/GettableCollectionInterface.php @@ -0,0 +1,58 @@ + + * @copyright Meritoo + */ +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); +} diff --git a/src/Contract/Collection/ReducibleCollectionInterface.php b/src/Contract/Collection/ReducibleCollectionInterface.php new file mode 100644 index 0000000..d2b2584 --- /dev/null +++ b/src/Contract/Collection/ReducibleCollectionInterface.php @@ -0,0 +1,29 @@ + + * @copyright Meritoo + */ +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; +} diff --git a/src/Contract/Collection/RemovableCollectionInterface.php b/src/Contract/Collection/RemovableCollectionInterface.php new file mode 100644 index 0000000..d0a95fa --- /dev/null +++ b/src/Contract/Collection/RemovableCollectionInterface.php @@ -0,0 +1,28 @@ + + * @copyright Meritoo + */ +interface RemovableCollectionInterface +{ + /** + * Removes given element + * + * @param mixed $element The element to remove + * @return void + */ + public function remove($element): void; +} diff --git a/src/Contract/Collection/VerifiableCollectionInterface.php b/src/Contract/Collection/VerifiableCollectionInterface.php new file mode 100644 index 0000000..98e7a67 --- /dev/null +++ b/src/Contract/Collection/VerifiableCollectionInterface.php @@ -0,0 +1,51 @@ + + * @copyright Meritoo + */ +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; +} diff --git a/tests/Collection/BaseCollectionTest.php b/tests/Collection/BaseCollectionTest.php index 5d6eab9..77c7170 100644 --- a/tests/Collection/BaseCollectionTest.php +++ b/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');