Incorporated feedback for zendframework#143

- Adds the method `addDefaultParam($templateName, $key, $value)` to
  `TemplateRendererInterface`; define a TEMPLATE_ALL constant.
  Replaces `addParameters()`.
- Renames `AddParametersTrait` to `DefaultParamsTrait`
  - Renames `$templateParams` to `$defaultParams`
  - Renames `addParameters()` to `addDefaultParam()`
- Updates PlatesRenderer to the interface changes.
- Modifies Twig and ZendView renderers to use the new trait.
- Wrote tests for the behavior for each renderer.

composer.json

@@ -14,6 +14,7 @@
         "container-interop/container-interop": "^1.1",
         "psr/http-message": "^1.0",
         "zendframework/zend-diactoros": "^1.1",
+        "zendframework/zend-stdlib": "^2.7",
         "zendframework/zend-stratigility": "^1.1"
     },
     "require-dev": {

src/Template/DefaultParamsTrait.php

@@ -0,0 +1,86 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @see       https://github.com/zendframework/zend-expressive for the canonical source repository
+ * @copyright Copyright (c) 2015 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   https://github.com/zendframework/zend-expressive/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Zend\Expressive\Template;
+
+use Traversable;
+use Zend\Expressive\Exception;
+use Zend\Stdlib\ArrayUtils;
+
+trait DefaultParamsTrait
+{
+    /**
+     * @var array
+     */
+    private $defaultParams = [];
+
+    /**
+     * Add a default parameter to use with a template.
+     *
+     * Use this method to provide a default parameter to use when a template is
+     * rendered. The parameter may be overridden by providing it when calling
+     * `render()`, or by calling this method again with a null value.
+     *
+     * The parameter will be specific to the template name provided. To make
+     * the parameter available to any template, pass the TEMPLATE_ALL constant
+     * for the template name.
+     *
+     * If the default parameter existed previously, subsequent invocations with
+     * the same template name and parameter name will overwrite.
+     *
+     * @param string $templateName Name of template to which the param applies;
+     *     use TEMPLATE_ALL to apply to all templates.
+     * @param string $param Param name.
+     * @param mixed $value
+     */
+    public function addDefaultParam($templateName, $param, $value)
+    {
+        if (! is_string($templateName) || empty($templateName)) {
+            throw new Exception\InvalidArgumentException(sprintf(
+                '$templateName must be a non-empty string; received %s',
+                (is_object($templateName) ? get_class($templateName) : gettype($templateName))
+            ));
+        }
+
+        if (! is_string($param) || empty($param)) {
+            throw new Exception\InvalidArgumentException(sprintf(
+                '$param must be a non-empty string; received %s',
+                (is_object($param) ? get_class($param) : gettype($param))
+            ));
+        }
+
+        if (! isset($this->defaultParams[$templateName])) {
+            $this->defaultParams[$templateName] = [];
+        }
+
+        $this->defaultParams[$templateName][$param] = $value;
+    }
+
+    /**
+     * Returns merged global, template-specific and given params
+     *
+     * @param string $template
+     * @param array $params
+     * @return array
+     */
+    private function mergeParams($template, array $params)
+    {
+        $globalDefaults = isset($this->defaultParams[TemplateRendererInterface::TEMPLATE_ALL])
+            ? $this->defaultParams[TemplateRendererInterface::TEMPLATE_ALL]
+            : [];
+
+        $templateDefaults = isset($this->defaultParams[$template])
+            ? $this->defaultParams[$template]
+            : [];
+
+        $defaults = ArrayUtils::merge($globalDefaults, $templateDefaults);
+
+        return ArrayUtils::merge($defaults, $params);
+    }
+}

src/Template/PlatesRenderer.php

@@ -11,6 +11,7 @@
 
 use League\Plates\Engine;
 use ReflectionProperty;
+use Zend\Expressive\Exception;
 
 /**
  * Template implementation bridging league/plates
@@ -89,17 +90,35 @@ public function getPaths()
     }
 
     /**
-     * Add parameters to template
+     * {@inheritDoc}
      *
-     * If no template name is given, the parameters will be added to all templates rendered
+     * Proxies to the Plate Engine's `addData()` method.
      *
-     * @param array|object $params
-     * @param string $name
+     * {@inheritDoc}
      */
-    public function addParameters($params, $name = null)
+    public function addDefaultParam($templateName, $param, $value)
     {
-        $params = $this->normalizeParams($params);
-        $this->template->addData($params, $name);
+        if (! is_string($templateName) || empty($templateName)) {
+            throw new Exception\InvalidArgumentException(sprintf(
+                '$templateName must be a non-empty string; received %s',
+                (is_object($templateName) ? get_class($templateName) : gettype($templateName))
+            ));
+        }
+
+        if (! is_string($param) || empty($param)) {
+            throw new Exception\InvalidArgumentException(sprintf(
+                '$param must be a non-empty string; received %s',
+                (is_object($param) ? get_class($param) : gettype($param))
+            ));
+        }
+
+        $params = [$param => $value];
+
+        if ($templateName === self::TEMPLATE_ALL) {
+            $templateName = null;
+        }
+
+        $this->template->addData($params, $templateName);
     }
 
 

src/Template/TemplateRendererInterface.php

@@ -14,6 +14,11 @@
  */
 interface TemplateRendererInterface
 {
+    /**
+     * @const string Value indicating all templates; used with `addDefaultParam()`.
+     */
+    const TEMPLATE_ALL = '*';
+
     /**
      * Render a template, optionally with parameters.
      *
@@ -45,12 +50,23 @@ public function addPath($path, $namespace = null);
     public function getPaths();
 
     /**
-     * Add parameters to template
+     * Add a default parameter to use with a template.
      *
-     * If no template name is given, the parameters will be added to all templates rendered
+     * Use this method to provide a default parameter to use when a template is
+     * rendered. The parameter may be overridden by providing it when calling
+     * `render()`, or by calling this method again with a null value.
      *
-     * @param array|object $params
-     * @param string|null $name
+     * The parameter will be specific to the template name provided. To make
+     * the parameter available to any template, pass the TEMPLATE_ALL constant
+     * for the template name.
+     *
+     * If the default parameter existed previously, subsequent invocations with
+     * the same template name and parameter name will overwrite.
+     *
+     * @param string $templateName Name of template to which the param applies;
+     *     use TEMPLATE_ALL to apply to all templates.
+     * @param string $param Param name.
+     * @param mixed $value
      */
-    public function addParameters($params, $name = null);
+    public function addDefaultParam($templateName, $param, $value);
 }

src/Template/TwigRenderer.php

@@ -18,8 +18,8 @@
  */
 class TwigRenderer implements TemplateRendererInterface
 {
-    use AddParametersTrait;
     use ArrayParametersTrait;
+    use DefaultParamsTrait;
 
     /**
      * @var string
@@ -90,8 +90,14 @@ private function getDefaultLoader()
      */
     public function render($name, $params = [])
     {
+        // Merge parameters based on requested template name
+        $params = $this->mergeParams($name, $this->normalizeParams($params));
+
         $name   = $this->normalizeTemplate($name);
-        $params = $this->mergeParams($this->normalizeParams($params), $name);
+
+        // Merge parameters based on normalized template name
+        $params = $this->mergeParams($name, $params);
+
         return $this->template->render($name, $params);
     }
 

src/Template/ZendViewRenderer.php

@@ -28,8 +28,8 @@
  */
 class ZendViewRenderer implements TemplateRendererInterface
 {
-    use AddParametersTrait;
     use ArrayParametersTrait;
+    use DefaultParamsTrait;
 
     /**
      * @var ViewModel
@@ -119,7 +119,7 @@ public function __construct(RendererInterface $renderer = null, $layout = null)
      */
     public function render($name, $params = [])
     {
-        $params = $this->mergeParams($this->normalizeParams($params), $name);
+        $params = $this->mergeParams($name, $this->normalizeParams($params));
         return $this->renderModel(
             $this->createModel($name, $params),
             $this->renderer

test/Template/PlatesRendererTest.php

@@ -190,7 +190,7 @@ public function testAddParameterToOneTemplate()
         $renderer = new PlatesRenderer();
         $renderer->addPath(__DIR__ . '/TestAsset');
         $name = 'Plates';
-        $renderer->addParameters(['name' => $name], 'plates');
+        $renderer->addDefaultParam('plates', 'name', $name);
         $result = $renderer->render('plates');
         $content = file_get_contents(__DIR__ . '/TestAsset/plates.php');
         $content= str_replace('<?=$this->e($name)?>', $name, $content);
@@ -213,7 +213,7 @@ public function testAddSharedParameters()
         $renderer = new PlatesRenderer();
         $renderer->addPath(__DIR__ . '/TestAsset');
         $name = 'Plates';
-        $renderer->addParameters(['name' => $name]);
+        $renderer->addDefaultParam($template::TEMPLATE_ALL, 'name', $name);
         $result = $renderer->render('plates');
         $content = file_get_contents(__DIR__ . '/TestAsset/plates.php');
         $content= str_replace('<?=$this->e($name)?>', $name, $content);
@@ -230,8 +230,8 @@ public function testOverrideSharedParametersPerTemplate()
         $renderer->addPath(__DIR__ . '/TestAsset');
         $name = 'Plates';
         $name2 = 'Saucers';
-        $renderer->addParameters(['name' => $name]);
-        $renderer->addParameters(['name' => $name2], 'plates-2');
+        $renderer->addDefaultParam($template::TEMPLATE_ALL, 'name', $name);
+        $renderer->addDefaultParam('plates-2', 'name', $name2);
         $result = $renderer->render('plates');
         $content = file_get_contents(__DIR__ . '/TestAsset/plates.php');
         $content= str_replace('<?=$this->e($name)?>', $name, $content);
@@ -248,7 +248,7 @@ public function testOverrideSharedParametersAtRender()
         $renderer->addPath(__DIR__ . '/TestAsset');
         $name = 'Plates';
         $name2 = 'Saucers';
-        $renderer->addParameters(['name' => $name]);
+        $renderer->addDefaultParam($template::TEMPLATE_ALL, 'name', $name);
         $result = $renderer->render('plates', ['name' => $name2]);
         $content = file_get_contents(__DIR__ . '/TestAsset/plates.php');
         $content= str_replace('<?=$this->e($name)?>', $name2, $content);

test/Template/TestAsset/twig-2.html

@@ -0,0 +1,3 @@
+<h1>This is a second template file for Twig</h1>
+
+<p>You are using <strong>{{ name }}</strong>!</p>

test/Template/TestAsset/zendview-2.phtml

@@ -0,0 +1,3 @@
+<h1>This is a second template file for ZendView</h1>
+
+<p>You are using <strong><?php echo $name ?></strong>!</p>

test/Template/TwigRendererTest.php

@@ -175,4 +175,66 @@ public function testResolvesNamespacedTemplateWithSuffix()
 
         $this->assertSame($expected, $test);
     }
+
+    public function testAddParameterToOneTemplate()
+    {
+        $template = new TwigRenderer();
+        $template->addPath(__DIR__ . '/TestAsset');
+        $name = 'Twig';
+        $template->addDefaultParam('twig', 'name', $name);
+        $result = $template->render('twig');
+
+        $content = file_get_contents(__DIR__ . '/TestAsset/twig.html');
+        $content = str_replace('{{ name }}', $name, $content);
+        $this->assertEquals($content, $result);
+    }
+
+    public function testAddSharedParameters()
+    {
+        $template = new TwigRenderer();
+        $template->addPath(__DIR__ . '/TestAsset');
+        $name = 'Twig';
+        $template->addDefaultParam($template::TEMPLATE_ALL, 'name', $name);
+        $result = $template->render('twig');
+        $content = file_get_contents(__DIR__ . '/TestAsset/twig.html');
+        $content = str_replace('{{ name }}', $name, $content);
+        $this->assertEquals($content, $result);
+
+        $result = $template->render('twig-2');
+        $content = file_get_contents(__DIR__ . '/TestAsset/twig-2.html');
+        $content = str_replace('{{ name }}', $name, $content);
+        $this->assertEquals($content, $result);
+    }
+
+    public function testOverrideSharedParametersPerTemplate()
+    {
+        $template = new TwigRenderer();
+        $template->addPath(__DIR__ . '/TestAsset');
+        $name = 'Twig';
+        $name2 = 'Template';
+        $template->addDefaultParam($template::TEMPLATE_ALL, 'name', $name);
+        $template->addDefaultParam('twig-2', 'name', $name2);
+        $result = $template->render('twig');
+        $content = file_get_contents(__DIR__ . '/TestAsset/twig.html');
+        $content = str_replace('{{ name }}', $name, $content);
+        $this->assertEquals($content, $result);
+
+        $result = $template->render('twig-2');
+        $content = file_get_contents(__DIR__ . '/TestAsset/twig-2.html');
+        $content = str_replace('{{ name }}', $name2, $content);
+        $this->assertEquals($content, $result);
+    }
+
+    public function testOverrideSharedParametersAtRender()
+    {
+        $template = new TwigRenderer();
+        $template->addPath(__DIR__ . '/TestAsset');
+        $name = 'Twig';
+        $name2 = 'Template';
+        $template->addDefaultParam($template::TEMPLATE_ALL, 'name', $name);
+        $result = $template->render('twig', ['name' => $name2]);
+        $content = file_get_contents(__DIR__ . '/TestAsset/twig.html');
+        $content = str_replace('{{ name }}', $name2, $content);
+        $this->assertEquals($content, $result);
+    }
 }