Merge branch 'develop'

Merged develop to master in preparation for 0.3.0 release.

Author: weierophinney

CHANGELOG.md

@@ -2,11 +2,20 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 0.2.2 - TBD
+## 0.3.0 - 2015-09-12
 
 ### Added
 
-- Nothing.
+- [#128](https://github.com/zendframework/zend-expressive/pull/128) adds
+  container factories for each supported template implementation:
+  - `Zend\Expressive\Container\Template\PlatesFactory`
+  - `Zend\Expressive\Container\Template\TwigFactory`
+  - `Zend\Expressive\Container\Template\ZendViewFactory`
+- [#128](https://github.com/zendframework/zend-expressive/pull/128) adds
+  custom `url` and `serverUrl` zend-view helper implementations, to allow
+  integration with any router and with PSR-7 URI instances. The newly
+  added `ZendViewFactory` will inject these into the `HelperPluginManager` by
+  default.
 
 ### Deprecated
 
@@ -18,7 +27,9 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Fixed
 
-- Nothing.
+- [#128](https://github.com/zendframework/zend-expressive/pull/128) fixes an
+  expectation in the `WhoopsErrorHandler` tests to ensure the tests can run
+  successfully.
 
 ## 0.2.1 - 2015-09-10
 

doc/book/container/factories.md

@@ -203,3 +203,107 @@ It consumes the following `config` structure:
 
 The `editor` value must be a known editor name (see the Whoops documentation for
 pre-configured editor types), a callable, or a service name to use.
+
+## PlatesFactory
+
+- **Provides**: `Zend\Expressive\Template\Plates`
+- **FactoryName**: `Zend\Expressive\Container\Template\PlatesFactory`
+- **Suggested Name**: `Zend\Expressive\Template\TemplateInterface`
+- **Requires**: no additional services are required.
+- **Optional**:
+    - `config`, an array or `ArrayAccess` instance. This will be used to further
+      configure the `Plates` instance, specifically with the filename extension
+      to use, and paths to inject.
+
+It consumes the following `config` structure:
+
+```php
+'templates' => [
+    'extension' => 'file extension used by templates; defaults to html',
+    'paths' => [
+        // namespace / path pairs
+        //
+        // Numeric namespaces imply the default/main namespace. Paths may be
+        // strings or arrays of string paths to associate with the namespace.
+    ],
+]
+```
+
+One note: Due to a limitation in the Plates engine, you can only map one path
+per namespace when using Plates.
+
+## TwigFactory
+
+- **Provides**: `Zend\Expressive\Template\Twig`
+- **FactoryName**: `Zend\Expressive\Container\Template\TwigFactory`
+- **Suggested Name**: `Zend\Expressive\Template\TemplateInterface`
+- **Requires**: no additional services are required.
+- **Optional**:
+    - `Zend\Expressive\Router\RouterInterface`; if found, it will be used to
+      seed a `Zend\Expressive\Template\Twig\TwigExtension` instance for purposes
+      of rendering application URLs.
+    - `config`, an array or `ArrayAccess` instance. This will be used to further
+      configure the `Twig` instance, specifically with the filename extension,
+      paths to assets (and default asset version to use), and template paths to
+      inject.
+
+It consumes the following `config` structure:
+
+```php
+'debug' => boolean,
+'templates' => [
+    'cache_dir' => 'path to cached templates',
+    'assets_url' => 'base URL for assets',
+    'assets_version' => 'base version for assets',
+    'extension' => 'file extension used by templates; defaults to html.twig',
+    'paths' => [
+        // namespace / path pairs
+        //
+        // Numeric namespaces imply the default/main namespace. Paths may be
+        // strings or arrays of string paths to associate with the namespace.
+    ],
+]
+```
+
+Whe `debug` is true, it disables caching, enables debug mode, enables strict
+variables, and enables auto reloading. The `assets_*` values are used to seed
+the `TwigExtension` instance (assuming the router was found).
+
+## ZendViewFactory
+
+- **Provides**: `Zend\Expressive\Template\ZendView`
+- **FactoryName**: `Zend\Expressive\Container\Template\ZendViewFactory`
+- **Suggested Name**: `Zend\Expressive\Template\TemplateInterface`
+- **Requires**: no additional services are required.
+    - `Zend\Expressive\Router\RouterInterface`, in order to inject the custom
+      url helper implementation.
+- **Optional**:
+    - `config`, an array or `ArrayAccess` instance. This will be used to further
+      configure the `ZendView` instance, specifically with the layout template
+      name, entries for a `TemplateMapResolver`, and and template paths to
+      inject.
+    - `Zend\View\HelperPluginManager`; if present, will be used to inject the
+      `PhpRenderer` instance.
+
+It consumes the following `config` structure:
+
+```php
+'templates' => [
+    'layout' => 'name of layout view to use, if any',
+    'map'    => [
+        // template => filename pairs
+    ],
+    'paths'  => [
+        // namespace / path pairs
+        //
+        // Numeric namespaces imply the default/main namespace. Paths may be
+        // strings or arrays of string paths to associate with the namespace.
+    ],
+]
+```
+
+When creating the `PhpRenderer` instance, it will inject it with a
+`Zend\View\HelperPluginManager` instance (either pulled from the container, or
+instantiated directly). It injects the helper plugin manager with custom url and
+serverurl helpers, `Zend\Expressive\Template\ZendView\UrlHelper` and
+`Zend\Expressive\Template\ZendView\ServerUrlHelper`, respetively.

doc/book/template/intro.md

@@ -28,3 +28,6 @@ We currently support:
 - [Plates](plates.md)
 - [Twig](twig.md)
 - [zend-view](zend-view.md)
+
+Each has an associated container factory; details are found in the
+[factories documentation](../container/factories.md).

doc/book/template/zend-view.md

@@ -145,6 +145,28 @@ $content = $templates->render('blog/entry', [
 ]);
 ```
 
+## Helpers
+
+Expressive provides overrides of specific view helpers in order to better
+integrate with PSR-7. These include:
+
+- `Zend\Expressive\Template\ZendView\UrlHelper`. This helper consumes the
+  application's `Zend\Expressive\Router\RouterInterface` instance in order
+  to generate URIs. It's signature is:
+  `url($routeName, array $substitutions = [])`
+- `Zend\Expressive\Template\ZendView\ServerUrlHelper`. This helper consumes the
+  URI from the application's request in order to provide fully qualified URIs.
+  It's signature is: `serverUrl($path = null)`.
+
+  To use this particular helper, you will need to inject it with the request URI
+  somewhere within your application:
+
+  ```php
+  $serverUrlHelper->setUri($request->getUri());
+  ```
+
+  We recommend doing this within a pre-pipeline middleware.
+
 ## Recommendations
 
 We recommend the following practices when using the zend-view adapter:

src/Container/Template/PlatesFactory.php

@@ -0,0 +1,67 @@
+<?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\Container\Template;
+
+use Interop\Container\ContainerInterface;
+use League\Plates\Engine as PlatesEngine;
+use Zend\Expressive\Template\Plates;
+
+/**
+ * Create and return a Plates template instance.
+ *
+ * Optionally uses the service 'config', which should return an array. This
+ * factory consumes the following structure:
+ *
+ * <code>
+ * 'templates' => [
+ *     'extension' => 'file extension used by templates; defaults to html',
+ *     'paths' => [
+ *         // namespace / path pairs
+ *         //
+ *         // Numeric namespaces imply the default/main namespace. Paths may be
+ *         // strings or arrays of string paths to associate with the namespace.
+ *     ],
+ * ]
+ * </code>
+ */
+class PlatesFactory
+{
+    /**
+     * @param ContainerInterface $container
+     * @return Plates
+     */
+    public function __invoke(ContainerInterface $container)
+    {
+        $config = $container->has('config') ? $container->get('config') : [];
+        $config = isset($config['templates']) ? $config['templates'] : [];
+
+        // Create the engine instance:
+        $engine = new PlatesEngine();
+
+        // Set file extension
+        if (isset($config['extension'])) {
+            $engine->setFileExtension($config['extension']);
+        }
+
+        // Inject engine
+        $plates = new Plates($engine);
+
+        // Add template paths
+        $allPaths = isset($config['paths']) && is_array($config['paths']) ? $config['paths'] : [];
+        foreach ($allPaths as $namespace => $paths) {
+            $namespace = is_numeric($namespace) ? null : $namespace;
+            foreach ((array) $paths as $path) {
+                $plates->addPath($path, $namespace);
+            }
+        }
+
+        return $plates;
+    }
+}

src/Container/Template/TwigFactory.php

@@ -0,0 +1,90 @@
+<?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\Container\Template;
+
+use Interop\Container\ContainerInterface;
+use Twig_Environment as TwigEnvironment;
+use Twig_Extension_Debug as TwigExtensionDebug;
+use Twig_Loader_Filesystem as TwigLoader;
+use Zend\Expressive\Router\RouterInterface;
+use Zend\Expressive\Template\Twig;
+
+/**
+ * Create and return a Twig template instance.
+ *
+ * Optionally uses the service 'config', which should return an array. This
+ * factory consumes the following structure:
+ *
+ * <code>
+ * 'debug' => boolean,
+ * 'templates' => [
+ *     'cache_dir' => 'path to cached templates',
+ *     'assets_url' => 'base URL for assets',
+ *     'assets_version' => 'base version for assets',
+ *     'extension' => 'file extension used by templates; defaults to html.twig',
+ *     'paths' => [
+ *         // namespace / path pairs
+ *         //
+ *         // Numeric namespaces imply the default/main namespace. Paths may be
+ *         // strings or arrays of string paths to associate with the namespace.
+ *     ],
+ * ]
+ * </code>
+ */
+class TwigFactory
+{
+    /**
+     * @param ContainerInterface $container
+     * @return Twig
+     */
+    public function __invoke(ContainerInterface $container)
+    {
+        $config   = $container->has('config') ? $container->get('config') : [];
+        $debug    = array_key_exists('debug', $config) ? (bool) $config['debug'] : false;
+        $config   = isset($config['templates']) ? $config['templates'] : [];
+        $cacheDir = isset($config['cache_dir']) ? $config['cache_dir'] : false;
+
+        // Create the engine instance
+        $loader      = new TwigLoader();
+        $environment = new TwigEnvironment($loader, [
+            'cache'            => $debug ? false : $cacheDir,
+            'debug'            => $debug,
+            'strict_variables' => $debug,
+            'auto_reload'      => $debug
+        ]);
+
+        // Add extensions
+        if ($container->has(RouterInterface::class)) {
+            $environment->addExtension(new Twig\TwigExtension(
+                $container->get(RouterInterface::class),
+                isset($config['assets_url']) ? $config['assets_url'] : '',
+                isset($config['assets_version']) ? $config['assets_version'] : ''
+            ));
+        }
+
+        if ($debug) {
+            $environment->addExtension(new TwigExtensionDebug());
+        }
+
+        // Inject environment
+        $twig = new Twig($environment, isset($config['extension']) ? $config['extension'] : 'html.twig');
+
+        // Add template paths
+        $allPaths = isset($config['paths']) && is_array($config['paths']) ? $config['paths'] : [];
+        foreach ($allPaths as $namespace => $paths) {
+            $namespace = is_numeric($namespace) ? null : $namespace;
+            foreach ((array) $paths as $path) {
+                $twig->addPath($path, $namespace);
+            }
+        }
+
+        return $twig;
+    }
+}