Update documentation of BaseCollection class

README.md

@@ -22,7 +22,7 @@ composer require meritoo/common-library
 # Usage
 
 1. [Base test case (with common methods and data providers)](docs/Base-test-case.md)
-2. [Collection of elements](docs/Collection/Collection.md)
+2. [Collection of elements](docs/Collection/BaseCollection.md)
 3. [Exceptions](docs/Static-methods.md)
 4. [Static methods](docs/Static-methods.md)
    1. [Arrays](docs/Static-methods/Arrays.md)

docs/Base-test-case.md

@@ -51,7 +51,7 @@ class MimeTypesTest extends BaseTestCase
 # More
 
 1. [**Base test case (with common methods and data providers)**](Base-test-case.md)
-2. [Collection of elements](Collection/Collection.md)
+2. [Collection of elements](Collection/BaseCollection.md)
 3. [Templates](Collection/Templates.md)
 4. [Exceptions](Exceptions.md)
 5. [Static methods](Static-methods.md)

docs/Collection/BaseCollection.md

@@ -2,15 +2,16 @@
 
 Common and useful classes, methods, exceptions etc.
 
-# Collection
+# BaseCollection
 
 ### Namespace
 
-`Meritoo\Common\Collection\Collection`
+`Meritoo\Common\Collection\BaseCollection`
 
 ### Info
 
-It's a set of some elements, e.g. objects. It's iterable and countable. Provides very useful methods. Some of them:
+It's a set of some elements with the same type, e.g. objects. It's iterable and countable. Provides very useful
+methods. Some of them:
 - `getFirst()` - returns the first element in the collection
 - `getLast()` - returns the last element in the collection
 - `isEmpty()` - returns information if collection is empty
@@ -19,21 +20,49 @@ It's a set of some elements, e.g. objects. It's iterable and countable. Provides
 - `prepend($element)` - prepends given element (adds given element at the beginning of collection)
 - `remove($element)` - removes given element
 
-Examples of usage below.
+### Implementation
 
-### An empty collection
+You have to implement:
 
 ```php
-use Meritoo\Common\Collection\Collection;
-
-$emptyCollection = new Collection();
-var_dump($emptyCollection->isEmpty()); // bool(true)
+abstract protected function isValidType($element): bool;
 ```
 
-### Simple collection
+This method verifies 1 element before it will be added to collection. Returns information if the element has valid,
+expected type.
+
+Example (from `Meritoo\Common\Collection\Templates` class):
 
 ```php
-use Meritoo\Common\Collection\Collection;
+protected function isValidType($element): bool
+{
+    return $element instanceof Template;
+}
+```
+
+### Methods to overwrite
+
+You can, if you wish, overwrite these methods:
+
+1. To prepare elements used to initialize the collection in your own way:
+
+    ```php
+    protected function prepareElements(array $elements): array
+    ```
+
+2. To validate type of elements in your own way:
+
+    ```php
+    protected function getElementsWithValidType(array $elements): array
+    ```
+
+### Examples of usage
+
+```php
+use Meritoo\Common\Collection\StringCollection;
+
+$emptyCollection = new StringCollection();
+var_dump($emptyCollection->isEmpty()); // bool(true)
 
 $elements = [
     'lorem',
@@ -42,14 +71,14 @@ $elements = [
     345 => 'sit',
 ];
 
-$simpleCollection = new Collection($elements);
+$simpleCollection = new StringCollection($elements);
 var_dump($simpleCollection->has('dolor')); // bool(true)
 ```
 
 # More
 
 1. [Base test case (with common methods and data providers)](../Base-test-case.md)
-2. [**Collection of elements**](Collection.md)
+2. [**Collection of elements**](BaseCollection.md)
 3. [Templates](Templates.md)
 4. [Exceptions](../Exceptions.md)
 5. [Static methods](../Static-methods.md)

docs/Collection/Templates.md

@@ -54,7 +54,7 @@ Throws an `Meritoo\Common\Exception\ValueObject\Template\TemplateNotFoundExcepti
 # More
 
 1. [Base test case (with common methods and data providers)](../Base-test-case.md)
-2. [Collection of elements](Collection.md)
+2. [Collection of elements](BaseCollection.md)
 3. [**Templates**](Templates.md)
 4. [Exceptions](../Exceptions.md)
 5. [Static methods](../Static-methods.md)

docs/Exceptions.md

@@ -54,7 +54,7 @@ class UnknownSimpleTypeException extends UnknownTypeException
 # More
 
 1. [Base test case (with common methods and data providers)](Base-test-case.md)
-2. [Collection of elements](Collection/Collection.md)
+2. [Collection of elements](Collection/BaseCollection.md)
 3. [Templates](Collection/Templates.md)
 4. [**Exceptions**](Exceptions.md)
 5. [Static methods](Static-methods.md)

docs/Static-methods.md

@@ -16,7 +16,7 @@ var_dump($firstElement); // string(5) "lorem"
 # More
 
 1. [Base test case (with common methods and data providers)](Base-test-case.md)
-2. [Collection of elements](Collection/Collection.md)
+2. [Collection of elements](Collection/BaseCollection.md)
 3. [Templates](Collection/Templates.md)
 4. [Exceptions](Exceptions.md)
 5. [**Static methods**](Static-methods.md)

docs/Static-methods/Arrays.md

@@ -95,7 +95,7 @@ File: `src/Utilities/Arrays.php`
 # More
 
 1. [Base test case (with common methods and data providers)](../Base-test-case.md)
-2. [Collection of elements](../Collection/Collection.md)
+2. [Collection of elements](../Collection/BaseCollection.md)
 3. [Templates](../Collection/Templates.md)
 4. [Exceptions](../Exceptions.md)
 5. [Static methods](../Static-methods.md)

docs/Static-methods/Regex.md

@@ -87,7 +87,7 @@ File: `src/Utilities/Regex.php`
 # More
 
 1. [Base test case (with common methods and data providers)](../Base-test-case.md)
-2. [Collection of elements](../Collection/Collection.md)
+2. [Collection of elements](../Collection/BaseCollection.md)
 3. [Templates](../Collection/Templates.md)
 4. [Exceptions](../Exceptions.md)
 5. [Static methods](../Static-methods.md)

docs/Static-methods/Uri.md

@@ -35,7 +35,7 @@ File: `src/Utilities/Uri.php`
 # More
 
 1. [Base test case (with common methods and data providers)](../Base-test-case.md)
-2. [Collection of elements](../Collection/Collection.md)
+2. [Collection of elements](../Collection/BaseCollection.md)
 3. [Templates](../Collection/Templates.md)
 4. [Exceptions](../Exceptions.md)
 5. [Static methods](../Static-methods.md)

docs/Value-Objects.md

@@ -338,7 +338,7 @@ $asString = (string)$version; // "1.0.2"
 # More
 
 1. [Base test case (with common methods and data providers)](Base-test-case.md)
-2. [Collection of elements](Collection/Collection.md)
+2. [Collection of elements](Collection/BaseCollection.md)
 3. [Templates](Collection/Templates.md)
 4. [Exceptions](Exceptions.md)
 5. [Static methods](Static-methods.md)