Using Twig

Twig is a template language and engine provided as a standalone component by SensioLabs. It provides:

We provide a TemplateRendererInterface wrapper for Twig via Zend\Expressive\Twig\TwigRenderer.

Installing Twig

To use the Twig wrapper, you must first install the Twig integration:

$ composer require zendframework/zend-expressive-twigrenderer

Using the wrapper

If instantiated without arguments, Zend\Expressive\Twig\TwigRenderer will create an instance of the Twig engine, which it will then proxy to.

use Zend\Expressive\Twig\TwigRenderer;

$renderer = new TwigRenderer();

Alternately, you can instantiate and configure the engine yourself, and pass it to the Zend\Expressive\Twig\TwigRenderer constructor:

use Twig_Environment;
use Twig_Loader_Array;
use Zend\Expressive\Twig\TwigRenderer;

// Create the engine instance:
$loader = new Twig_Loader_Array(include 'config/templates.php');
$twig = new Twig_Environment($loader);

// Configure it:
$twig->addExtension(new CustomExtension());
$twig->loadExtension(new CustomExtension();

// Inject:
$renderer = new TwigRenderer($twig);

Included extensions and functions

The included Twig extension adds support for url generation. The extension is automatically activated if the UrlHelper and ServerUrlHelper are registered with the container.

The following template functions are exposed:

twig {{ path('article_show', {'id': '3'}) }} Generates: /article/3

twig {{ url('article_show', {'id': '3'}, {'foo': 'bar'}, 'fragment') }} Generates: http://example.com/article/3?foo=bar#fragment

twig {{ absolute_url('path/to/something') }} Generates: http://example.com/path/to/something

twig {{ asset('path/to/asset/name.ext', version=3) }} Generates: path/to/asset/name.ext?v=3

To get the absolute url for an asset:

twig {{ absolute_url(asset('path/to/asset/name.ext', version=3)) }} Generates: http://example.com/path/to/asset/name.ext?v=3

Configuration

The following details configuration specific to Twig, as consumed by the TwigRendererFactory:

return [
    'templates' => [
        '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.
        ],
    ],
    'twig' => [
        'autoescape' => 'html', // Auto-escaping strategy [html|js|css|url|false]
        'cache_dir' => 'path to cached templates',
        'assets_url' => 'base URL for assets',
        'assets_version' => 'base version for assets',
        'extensions' => [
            // extension service names or instances
        ],
        'globals' => [
            // Global variables passed to twig templates
            'ga_tracking' => 'UA-XXXXX-X'
        ],
        'optimizations' => -1, // -1: Enable all (default), 0: disable optimizations
        'runtime_loaders' => [
            // runtime loader names or instances
        ],
        'timezone' => 'default timezone identifier, e.g. America/New_York',
    ],
];

When specifying the twig.extensions values, always use fully qualified class names or actual extension instances to ensure compatibility with any version of Twig used. Version 2 of Twig requires that a fully qualified class name is used, and not a short-name alias.