Template with placeholders that may be filled by real data

src/Exception/ValueObject/Template/InvalidContentException.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 content of template is invalid
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+class InvalidContentException extends Exception
+{
+    /**
+     * Creates an exception
+     *
+     * @param string $content Invalid content of template
+     * @return InvalidContentException
+     */
+    public static function create(string $content): InvalidContentException
+    {
+        $template = 'Content of template \'%s\' is invalid. Did you use string with 1 placeholder at least?';
+        $message = sprintf($template, $content);
+
+        return new static($message);
+    }
+}

src/Exception/ValueObject/Template/NotEnoughValuesException.php

@@ -0,0 +1,39 @@
+<?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 there is not enough values to fill all placeholders in template
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+class NotEnoughValuesException extends Exception
+{
+    /**
+     * Creates an exception
+     *
+     * @param string $content           Invalid content of template
+     * @param int    $valuesCount       Count of values
+     * @param int    $placeholdersCount Count of placeholders
+     * @return NotEnoughValuesException
+     */
+    public static function create(string $content, int $valuesCount, int $placeholdersCount): NotEnoughValuesException
+    {
+        $template = 'Not enough values (%d) to fill all placeholders (%d) in template \'%s\'. Did you provide all'
+            . ' required values?';
+        $message = sprintf($template, $valuesCount, $placeholdersCount, $content);
+
+        return new static($message);
+    }
+}

src/ValueObject/Template.php

@@ -0,0 +1,151 @@
+<?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\ValueObject;
+
+use Meritoo\Common\Exception\ValueObject\Template\InvalidContentException;
+use Meritoo\Common\Exception\ValueObject\Template\NotEnoughValuesException;
+
+/**
+ * Template with placeholders that may be filled by real data
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+class Template
+{
+    /**
+     * Tag used at beginning and ending of placeholder
+     *
+     * @var string
+     */
+    private const PLACEHOLDER_TAG = '%';
+
+    /**
+     * Raw string with placeholders (content of the template)
+     *
+     * @var string
+     */
+    private $content;
+
+    /**
+     * Class constructor
+     *
+     * @param string $content Raw string with placeholders (content of the template)
+     * @throws InvalidContentException
+     */
+    public function __construct(string $content)
+    {
+        if (!static::isValid($content)) {
+            throw InvalidContentException::create($content);
+        }
+
+        $this->content = $content;
+    }
+
+    /**
+     * Returns content of the template filled with given values (by replacing placeholders with their proper values)
+     *
+     * @param array $values Pairs of key-value where: key - name of placeholder, value - value of the placeholder
+     * @throws NotEnoughValuesException
+     * @return string
+     */
+    public function fill(array $values): string
+    {
+        $placeholders = static::getPlaceholders($this->content);
+        $valuesCount = count($values);
+        $placeholdersCount = count($placeholders[0]);
+
+        // Oops, not enough values (iow. more placeholders than values)
+        if ($placeholdersCount > $valuesCount) {
+            throw NotEnoughValuesException::create($this->content, $valuesCount, $placeholdersCount);
+        }
+
+        $result = $this->content;
+
+        foreach ($placeholders[0] as $index => $placeholder) {
+            $placeholderName = $placeholders[1][$index];
+
+            if (isset($values[$placeholderName])) {
+                $value = $values[$placeholderName];
+                $result = str_replace($placeholder, $value, $result);
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * Returns information if given template is valid
+     *
+     * @param string $content Raw string with placeholders to validate (content of the template)
+     * @return bool
+     */
+    private static function isValid(string $content): bool
+    {
+        if ('' === $content) {
+            return false;
+        }
+
+        return (bool)preg_match_all(static::getPlaceholderPattern(), $content);
+    }
+
+    /**
+     * Returns placeholders of given template
+     *
+     * @param string $content Content of template
+     * @return array
+     */
+    private static function getPlaceholders(string $content): array
+    {
+        $result = [];
+        $matchCount = preg_match_all(static::getPlaceholderPattern(), $content, $result);
+
+        if (false !== $matchCount && 0 < $matchCount) {
+            foreach ($result as $index => $placeholders) {
+                $result[$index] = array_unique($placeholders);
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * Returns regular expression that defines format of placeholder
+     *
+     * Expectations:
+     * - surrounded by the placeholder's tags (at beginning and at the end)
+     * - at least 1 character
+     * - no placeholder's tag inside name of placeholder
+     *
+     * Invalid placeholders:
+     * - test
+     * - test%
+     * - % test%
+     *
+     * Valid placeholders:
+     * - %test%
+     * - %another_test%
+     * - %another-test%
+     * - %anotherTest%
+     * - %another test%
+     *
+     * @return string
+     */
+    private static function getPlaceholderPattern(): string
+    {
+        return sprintf(
+            '/%s([^%s]+)%s/',
+            static::PLACEHOLDER_TAG,
+            static::PLACEHOLDER_TAG,
+            static::PLACEHOLDER_TAG
+        );
+    }
+}

src/ValueObject/Version.php

@@ -108,7 +108,7 @@ class Version
      * @param string $version The version
      * @return Version|null
      */
-    public static function fromString($version)
+    public static function fromString(string $version)
     {
         $version = trim($version);