templating.rst

.. index::
   single: Templating
   single: Components; Templating

The Templating Component

The Templating component provides all the tools needed to build any kind of template system.

It provides an infrastructure to load template files and optionally monitor them for changes. It also provides a concrete template engine implementation using PHP with additional tools for escaping and separating templates into blocks and layouts.

Installation

$ composer require symfony/templating

Usage

.. seealso::

    This article explains how to use the Templating features as an independent
    component in any PHP application. Read the article about :doc:`templates </templates>`
    to learn about how to work with templates in Symfony applications.

The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point of the component. It needs a template name parser (:class:`Symfony\\Component\\Templating\\TemplateNameParserInterface`) to convert a template name to a template reference (:class:`Symfony\\Component\\Templating\\TemplateReferenceInterface`). It also needs a template loader (:class:`Symfony\\Component\\Templating\\Loader\\LoaderInterface`) which uses the template reference to actually find and load the template:

use Symfony\Component\Templating\Loader\FilesystemLoader;
use Symfony\Component\Templating\PhpEngine;
use Symfony\Component\Templating\TemplateNameParser;

$filesystemLoader = new FilesystemLoader(__DIR__.'/views/%name%');

$templating = new PhpEngine(new TemplateNameParser(), $filesystemLoader);

echo $templating->render('hello.php', ['firstname' => 'Fabien']);

<!-- views/hello.php -->
Hello, <?= $firstname ?>!

The :method:`Symfony\\Component\\Templating\\PhpEngine::render` method parses the views/hello.php file and returns the output text. The second argument of render is an array of variables to use in the template. In this example, the result will be Hello, Fabien!.

Note

Templates will be cached in the memory of the engine. This means that if you render the same template multiple times in the same request, the template will only be loaded once from the file system.

The $view Variable

In all templates parsed by the PhpEngine, you get access to a mysterious variable called $view. That variable holds the current PhpEngine instance. That means you get access to a bunch of methods that make your life easier.

Including Templates

The best way to share a snippet of template code is to create a template that can then be included by other templates. As the $view variable is an instance of PhpEngine, you can use the render() method (which was used to render the template originally) inside the template to render another template:

<?php $names = ['Fabien', ...] ?>
<?php foreach ($names as $name) : ?>
    <?= $view->render('hello.php', ['firstname' => $name]) ?>
<?php endforeach ?>

Global Variables

Sometimes, you need to set a variable which is available in all templates rendered by an engine (like the $app variable when using the Symfony Framework). These variables can be set by using the :method:`Symfony\\Component\\Templating\\PhpEngine::addGlobal` method and they can be accessed in the template as normal variables:

$templating->addGlobal('ga_tracking', 'UA-xxxxx-x');

In a template:

<p>The google tracking code is: <?= $ga_tracking ?></p>

Caution!

The global variables cannot be called this or view, since they are already used by the PHP engine.

Note

The global variables can be overridden by a local variable in the template with the same name.

Output Escaping

When you render variables, you should probably escape them so that HTML or JavaScript code isn't written out to your page. This will prevent things like XSS attacks. To do this, use the :method:`Symfony\\Component\\Templating\\PhpEngine::escape` method:

<?= $view->escape($firstname) ?>

By default, the escape() method assumes that the variable is outputted within an HTML context. The second argument lets you change the context. For example, to output something inside JavaScript, use the js context:

<?= $view->escape($var, 'js') ?>

The component comes with an HTML and JS escaper. You can register your own escaper using the :method:`Symfony\\Component\\Templating\\PhpEngine::setEscaper` method:

$templating->setEscaper('css', function ($value) {
    // ... all CSS escaping

    return $escapedValue;
});

Helpers

The Templating component can be extended via helpers. Helpers are PHP objects that provide features useful in a template context. The component has one built-in helper:

• :doc:`/components/templating/slotshelper`

Before you can use these helpers, you need to register them using :method:`Symfony\\Component\\Templating\\PhpEngine::set`:

use Symfony\Component\Templating\Helper\SlotsHelper;
// ...

$templating->set(new SlotsHelper());

Custom Helpers

You can create your own helpers by creating a class which implements :class:`Symfony\\Component\\Templating\\Helper\\HelperInterface`. However, most of the time you'll extend :class:`Symfony\\Component\\Templating\\Helper\\Helper`.

The Helper has one required method: :method:`Symfony\\Component\\Templating\\Helper\\HelperInterface::getName`. This is the name that is used to get the helper from the $view object.

Creating a Custom Engine

Besides providing a PHP templating engine, you can also create your own engine using the Templating component. To do that, create a new class which implements the :class:`Symfony\\Component\\Templating\\EngineInterface`. This requires 3 method:

• :method:`render($name, array $parameters = []) <Symfony\\Component\\Templating\\EngineInterface::render>` - Renders a template
• :method:`exists($name) <Symfony\\Component\\Templating\\EngineInterface::exists>` - Checks if the template exists
• :method:`supports($name) <Symfony\\Component\\Templating\\EngineInterface::supports>` - Checks if the given template can be handled by this engine.

Using Multiple Engines

It is possible to use multiple engines at the same time using the :class:`Symfony\\Component\\Templating\\DelegatingEngine` class. This class takes a list of engines and acts just like a normal templating engine. The only difference is that it delegates the calls to one of the other engines. To choose which one to use for the template, the :method:`EngineInterface::supports() <Symfony\\Component\\Templating\\EngineInterface::supports>` method is used:

use Acme\Templating\CustomEngine;
use Symfony\Component\Templating\DelegatingEngine;
use Symfony\Component\Templating\PhpEngine;

$templating = new DelegatingEngine([
    new PhpEngine(...),
    new CustomEngine(...),
]);

Learn More

.. toctree::
    :maxdepth: 1
    :glob:

    /components/templating/*
    /templates
    /templating/*