Collection/storage of templates

README.md

@@ -17,7 +17,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-of-elements.md)
+2. [Collection of elements](docs/Collection/Collection.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

@@ -45,11 +45,12 @@ class MimeTypesTest extends BaseTestCase
 # More
 
 1. [**Base test case (with common methods and data providers)**](Base-test-case.md)
-2. [Collection of elements](Collection-of-elements.md)
+2. [Collection of elements](Collection/Collection.md)
-3. [Exceptions](Exceptions.md)
+3. [Templates](Collection/Templates.md)
-4. [Static methods](Static-methods.md)
+4. [Exceptions](Exceptions.md)
+5. [Static methods](Static-methods.md)
    1. [Arrays](Static-methods/Arrays.md)
    2. [Regex](Static-methods/Regex.md)
-5. [Value Objects](Value-Objects.md)
+6. [Value Objects](Value-Objects.md)
 
 [‹ Back to `Readme`](../README.md)

docs/Collection/Collection.md

@@ -2,9 +2,15 @@
 
 Common and useful classes, methods, exceptions etc.
 
-# Collection of elements
+# Collection
 
-Located here: `Meritoo\Common\Collection\Collection`. It's a set of some elements, e.g. objects. It's iterable and countable. Provides very useful methods. Some of them:
+### Namespace
+
+`Meritoo\Common\Collection\Collection`
+
+### Info
+
+It's a set of some elements, 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
@@ -42,12 +48,13 @@ var_dump($simpleCollection->has('dolor')); // bool(true)
 
 # More
 
-1. [Base test case (with common methods and data providers)](Base-test-case.md)
+1. [Base test case (with common methods and data providers)](../Base-test-case.md)
-2. [**Collection of elements**](Collection-of-elements.md)
+2. [**Collection of elements**](Collection.md)
-3. [Exceptions](Exceptions.md)
+3. [Templates](Templates.md)
-4. [Static methods](Static-methods.md)
+4. [Exceptions](../Exceptions.md)
-   1. [Arrays](Static-methods/Arrays.md)
+5. [Static methods](../Static-methods.md)
-   2. [Regex](Static-methods/Regex.md)
+   1. [Arrays](../Static-methods/Arrays.md)
-5. [Value Objects](Value-Objects.md)
+   2. [Regex](../Static-methods/Regex.md)
+6. [Value Objects](../Value-Objects.md)
 
-[‹ Back to `Readme`](../README.md)
+[‹ Back to `Readme`](../../README.md)

docs/Collection/Templates.md

@@ -0,0 +1,65 @@
+# Meritoo Common Library
+
+Common and useful classes, methods, exceptions etc.
+
+# Templates
+
+### Namespace
+
+`Meritoo\Common\Collection\Templates`
+
+### Info
+
+Collection/storage of templates, instance of `Meritoo\Common\ValueObject\Template` class.
+
+##### New instance
+
+New instance can be created using:
+
+1. Constructor:
+
+	```php
+    new Templates([
+    	'first' => new Template('First name: %first_name%'),
+        'last'  => new Template('Last name: %last_name%'),
+    ]);
+    ```
+
+2. Static method `fromArray(array $templates)` - creates and returns the collection from given array
+
+	```php
+	Templates::fromArray([
+    	'first' => 'First name: %first_name%',
+        'last'  => 'Last name: %last_name%',
+    ]);
+	```
+
+##### Methods
+
+Has all methods of parent class `Meritoo\Common\Collection\Collection` + `findTemplate(string $index)` method that finds and returns template with given index.
+
+Example of usage:
+
+```php
+$templates = new Templates([
+	'first' => new Template('First name: %first_name%'),
+    'last'  => new Template('Last name: %last_name%'),
+]);
+
+$template = $templates->findTemplate('first'); // new Template('First name: %first_name%')
+```
+
+Throws an `Meritoo\Common\Exception\ValueObject\Template\TemplateNotFoundException` exception if template with given index was not found.
+
+# More
+
+1. [Base test case (with common methods and data providers)](../Base-test-case.md)
+2. [Collection of elements](Collection.md)
+3. [**Templates**](Templates.md)
+4. [Exceptions](../Exceptions.md)
+5. [Static methods](../Static-methods.md)
+   1. [Arrays](../Static-methods/Arrays.md)
+   2. [Regex](../Static-methods/Regex.md)
+6. [Value Objects](../Value-Objects.md)
+
+[‹ Back to `Readme`](../../README.md)

docs/Exceptions.md

@@ -54,11 +54,12 @@ class UnknownSimpleTypeException extends UnknownTypeException
 # More
 
 1. [Base test case (with common methods and data providers)](Base-test-case.md)
-2. [Collection of elements](Collection-of-elements.md)
+2. [Collection of elements](Collection/Collection.md)
-3. [**Exceptions**](Exceptions.md)
+3. [Templates](Collection/Templates.md)
-4. [Static methods](Static-methods.md)
+4. [**Exceptions**](Exceptions.md)
+5. [Static methods](Static-methods.md)
    1. [Arrays](Static-methods/Arrays.md)
    2. [Regex](Static-methods/Regex.md)
-5. [Value Objects](Value-Objects.md)
+6. [Value Objects](Value-Objects.md)
 
 [‹ Back to `Readme`](../README.md)

docs/Static-methods.md

@@ -16,11 +16,12 @@ 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-of-elements.md)
+2. [Collection of elements](Collection/Collection.md)
-3. [Exceptions](Exceptions.md)
+3. [Templates](Collection/Templates.md)
-4. [**Static methods**](Static-methods.md)
+4. [Exceptions](Exceptions.md)
+5. [**Static methods**](Static-methods.md)
    1. [Arrays](Static-methods/Arrays.md)
    2. [Regex](Static-methods/Regex.md)
-5. [Value Objects](Value-Objects.md)
+6. [Value Objects](Value-Objects.md)
 
 [‹ Back to `Readme`](../README.md)

docs/Static-methods/Arrays.md

@@ -68,11 +68,12 @@ 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-of-elements.md)
+2. [Collection of elements](../Collection/Collection.md)
-3. [Exceptions](../Exceptions.md)
+3. [Templates](../Collection/Templates.md)
-4. [Static methods](../Static-methods.md)
+4. [Exceptions](../Exceptions.md)
+5. [Static methods](../Static-methods.md)
    1. [**Arrays**](Arrays.md)
    2. [Regex](Regex.md)
-5. [Value Objects](../Value-Objects.md)
+6. [Value Objects](../Value-Objects.md)
 
 [‹ Back to `Readme`](../../README.md)

docs/Static-methods/Regex.md

@@ -35,11 +35,12 @@ 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-of-elements.md)
+2. [Collection of elements](../Collection/Collection.md)
-3. [Exceptions](../Exceptions.md)
+3. [Templates](../Collection/Templates.md)
-4. [Static methods](../Static-methods.md)
+4. [Exceptions](../Exceptions.md)
+5. [Static methods](../Static-methods.md)
    1. [Arrays](../Static-methods/Arrays.md)
    2. [**Regex**](Regex.md)
-5. [Value Objects](../Value-Objects.md)
+6. [Value Objects](../Value-Objects.md)
 
 [‹ Back to `Readme`](../../README.md)

docs/Value-Objects.md

@@ -338,11 +338,12 @@ $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-of-elements.md)
+2. [Collection of elements](Collection/Collection.md)
-3. [Exceptions](Exceptions.md)
+3. [Templates](Collection/Templates.md)
-4. [Static methods](Static-methods.md)
+4. [Exceptions](Exceptions.md)
+5. [Static methods](Static-methods.md)
    1. [Arrays](Static-methods/Arrays.md)
    2. [Regex](Static-methods/Regex.md)
-5. [**Value Objects**](Value-Objects.md)
+6. [**Value Objects**](Value-Objects.md)
 
 [‹ Back to `Readme`](../README.md)

src/Collection/Templates.php

@@ -0,0 +1,65 @@
+<?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\Collection;
+
+use Meritoo\Common\Exception\ValueObject\Template\TemplateNotFoundException;
+use Meritoo\Common\ValueObject\Template;
+
+/**
+ * Collection/storage of templates
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+class Templates extends Collection
+{
+    /**
+     * Finds and returns template with given index
+     *
+     * @param string $index Index that contains required template
+     * @throws TemplateNotFoundException
+     * @return Template
+     */
+    public function findTemplate(string $index): Template
+    {
+        /* @var Template $template */
+        $template = $this->getByIndex($index);
+
+        if ($template instanceof Template) {
+            return $template;
+        }
+
+        // Oops, template not found
+        throw TemplateNotFoundException::create($index);
+    }
+
+    /**
+     * Creates and returns the collection from given array
+     *
+     * @param array $templates Pairs of key-value where: key - template's index, value - template's content
+     * @return Templates
+     */
+    public static function fromArray(array $templates): Templates
+    {
+        // No templates. Nothing to do.
+        if (empty($templates)) {
+            return new static();
+        }
+
+        $result = new static();
+
+        foreach ($templates as $index => $template) {
+            $result->add(new Template($template), $index);
+        }
+
+        return $result;
+    }
+}

src/Exception/ValueObject/Template/TemplateNotFoundException.php

@@ -0,0 +1,36 @@
+<?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\Exception\ValueObject\Template;
+
+use Exception;
+
+/**
+ * An exception used while template with given index was not found
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+class TemplateNotFoundException extends Exception
+{
+    /**
+     * Creates the exception
+     *
+     * @param string $index Index that should contain template, but it was not found
+     * @return TemplateNotFoundException
+     */
+    public static function create(string $index): TemplateNotFoundException
+    {
+        $template = 'Template with \'%s\' index was not found. Did you provide all required templates?';
+        $message = sprintf($template, $index);
+
+        return new static($message);
+    }
+}

tests/Collection/TemplatesTest.php

@@ -0,0 +1,188 @@
+<?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.
+ */
+
+namespace Meritoo\Test\Common\Collection;
+
+use Generator;
+use Meritoo\Common\Collection\Templates;
+use Meritoo\Common\Exception\ValueObject\Template\TemplateNotFoundException;
+use Meritoo\Common\Test\Base\BaseTestCase;
+use Meritoo\Common\Type\OopVisibilityType;
+use Meritoo\Common\ValueObject\Template;
+
+/**
+ * Test case for the collection/storage of templates
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ *
+ * @internal
+ * @covers    \Meritoo\Common\Collection\Templates
+ */
+class TemplatesTest extends BaseTestCase
+{
+    public function testConstructor(): void
+    {
+        static::assertConstructorVisibilityAndArguments(
+            Templates::class,
+            OopVisibilityType::IS_PUBLIC,
+            1
+        );
+    }
+
+    /**
+     * @param string    $description Description of test
+     * @param array     $templates   Pairs of key-value where: key - template's index, value - template's content
+     * @param Templates $expected    Expected collection/storage of templates
+     *
+     * @dataProvider provideArrayWithTemplates
+     */
+    public function testFromArray(string $description, array $templates, Templates $expected): void
+    {
+        static::assertEquals($expected, Templates::fromArray($templates), $description);
+    }
+
+    public function testFindTemplateUsingEmptyCollection(): void
+    {
+        $template = 'Template with \'%s\' index was not found. Did you provide all required templates?';
+        $message = sprintf($template, 'test');
+
+        $this->expectException(TemplateNotFoundException::class);
+        $this->expectExceptionMessage($message);
+
+        $templates = new Templates();
+        $templates->findTemplate('test');
+    }
+
+    /**
+     * @param Templates $templates       All templates
+     * @param string    $index           Index that contains required template
+     * @param string    $expectedMessage Expected message of exception
+     *
+     * @dataProvider provideTemplatesWithNotExistingIndex
+     */
+    public function testFindTemplateUsingNotExistingIndex(
+        Templates $templates,
+        string $index,
+        string $expectedMessage
+    ): void {
+        $this->expectException(TemplateNotFoundException::class);
+        $this->expectExceptionMessage($expectedMessage);
+
+        $templates->findTemplate($index);
+    }
+
+    /**
+     * @param string    $description Description of test
+     * @param Templates $templates   All templates
+     * @param string    $index       Index that contains required template
+     * @param Template  $expected    Expected template
+     *
+     * @dataProvider provideTemplatesToFind
+     */
+    public function testFindTemplate(string $description, Templates $templates, string $index, Template $expected): void
+    {
+        static::assertEquals($expected, $templates->findTemplate($index), $description);
+    }
+
+    public function provideArrayWithTemplates(): ?Generator
+    {
+        yield[
+            'An empty array',
+            [],
+            new Templates(),
+        ];
+
+        yield[
+            'Number-based indexes',
+            [
+                'First name: %first_name%',
+                'Last name: %last_name%',
+            ],
+            new Templates([
+                new Template('First name: %first_name%'),
+                new Template('Last name: %last_name%'),
+            ]),
+        ];
+
+        yield[
+            'String-based indexes',
+            [
+                'first' => 'First name: %first_name%',
+                'last'  => 'Last name: %last_name%',
+            ],
+            new Templates([
+                'first' => new Template('First name: %first_name%'),
+                'last'  => new Template('Last name: %last_name%'),
+            ]),
+        ];
+    }
+
+    public function provideTemplatesWithNotExistingIndex(): ?Generator
+    {
+        $template = 'Template with \'%s\' index was not found. Did you provide all required templates?';
+
+        yield[
+            new Templates(),
+            'test',
+            sprintf($template, 'test'),
+        ];
+
+        yield[
+            new Templates([
+                'first' => new Template('First name: %first_name%'),
+                'last'  => new Template('Last name: %last_name%'),
+            ]),
+            'test',
+            sprintf($template, 'test'),
+        ];
+
+        yield[
+            new Templates([
+                'first' => new Template('First name: %first_name%'),
+                'last'  => new Template('Last name: %last_name%'),
+            ]),
+            '',
+            sprintf($template, ''),
+        ];
+
+        yield[
+            new Templates([
+                'first' => new Template('First name: %first_name%'),
+                'last'  => new Template('Last name: %last_name%'),
+            ]),
+            '4',
+            sprintf($template, 4),
+        ];
+    }
+
+    public function provideTemplatesToFind(): ?Generator
+    {
+        yield[
+            '2 templates only',
+            new Templates([
+                'first' => new Template('First name: %first_name%'),
+                'last'  => new Template('Last name: %last_name%'),
+            ]),
+            'first',
+            new Template('First name: %first_name%'),
+        ];
+
+        yield[
+            'Different indexes',
+            new Templates([
+                'first' => new Template('First name: %first_name%'),
+                'last'  => new Template('Last name: %last_name%'),
+                1       => new Template('Hi %name%, how are you?'),
+                '2'     => new Template('Your score is: %score%'),
+            ]),
+            '1',
+            new Template('Hi %name%, how are you?'),
+        ];
+    }
+}

tests/Exception/ValueObject/Template/TemplateNotFoundExceptionTest.php

@@ -0,0 +1,71 @@
+<?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.
+ */
+
+namespace Meritoo\Test\Common\Exception\ValueObject\Template;
+
+use Generator;
+use Meritoo\Common\Exception\ValueObject\Template\TemplateNotFoundException;
+use Meritoo\Common\Test\Base\BaseTestCase;
+use Meritoo\Common\Type\OopVisibilityType;
+
+/**
+ * Test case of an exception used while template with given index was not found
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ *
+ * @internal
+ * @covers    \Meritoo\Common\Exception\ValueObject\Template\TemplateNotFoundException
+ */
+class TemplateNotFoundExceptionTest extends BaseTestCase
+{
+    public function testConstructor(): void
+    {
+        static::assertConstructorVisibilityAndArguments(
+            TemplateNotFoundException::class,
+            OopVisibilityType::IS_PUBLIC,
+            3
+        );
+    }
+
+    /**
+     * @param string                    $description Description of test
+     * @param string                    $index       Index that should contain template, but it was not found
+     * @param TemplateNotFoundException $expected    Expected exception
+     *
+     * @dataProvider provideIndexAndException
+     */
+    public function testCreate(string $description, string $index, TemplateNotFoundException $expected): void
+    {
+        $created = TemplateNotFoundException::create($index);
+        static::assertEquals($expected, $created, $description);
+    }
+
+    public function provideIndexAndException(): ?Generator
+    {
+        $template = 'Template with \'%s\' index was not found. Did you provide all required templates?';
+
+        yield[
+            'An empty string',
+            '',
+            new TemplateNotFoundException(sprintf($template, '')),
+        ];
+
+        yield[
+            'Non-empty string',
+            'test',
+            new TemplateNotFoundException(sprintf($template, 'test')),
+        ];
+
+        yield[
+            'Integer',
+            '2',
+            new TemplateNotFoundException(sprintf($template, 2)),
+        ];
+    }
+}