The Templating Component

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

It provides an infrastructure to load template files and optionallymonitor them for changes. It also provides a concrete template engineimplementation using PHP with additional tools for escaping and separatingtemplates into blocks and layouts.

Installation

$ composer require symfony/templating

Note

If you install this component outside of a Symfony application, you mustrequire the vendor/autoload.php file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Usage

This article explains how to use the Templating features as an independentcomponent in any PHP application. Read the article about templatesto learn about how to work with templates in Symfony applications.

The PhpEngine class is the entry pointof the component. It needs atemplate name parser (TemplateNameParserInterface)to convert a template name to atemplate reference (TemplateReferenceInterface).It also needs a template 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 render() method parsesthe views/hello.php file and returns the output text. The second argumentof render is an array of variables to use in the template. In thisexample, the result will be Hello, Fabien!.

Note

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

The $view Variable

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

Including Templates

The best way to share a snippet of template code is to create a template thatcan then be included by other templates. As the $view variable is aninstance of PhpEngine, you can use the render() method (which was usedto 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 templatesrendered by an engine (like the $app variable when using the SymfonyFramework). These variables can be set by using theaddGlobal() method and theycan 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 arealready used by the PHP engine.

Note

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

Output Escaping

When you render variables, you should probably escape them so that HTML orJavaScript code isn't written out to your page. This will prevent things likeXSS attacks. To do this, use theescape() method:

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

By default, the escape() method assumes that the variable is outputtedwithin an HTML context. The second argument lets you change the context. Forexample, 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 ownescaper using thesetEscaper() method:

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

Helpers

The Templating component can be extended via helpers. Helpers are PHP objectsthat provide features useful in a template context. The component has onebuilt-in helper:

• Slots HelperBefore you can use these helpers, you need to register them usingset():

use Symfony\Component\Templating\Helper\SlotsHelper;
// ...
 
$templating->set(new SlotsHelper());

Custom Helpers

You can create your own helpers by creating a class which implementsHelperInterface. However,most of the time you'll extendHelper.

The Helper has one required method: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 engineusing the Templating component. To do that, create a new class whichimplements the EngineInterface. Thisrequires 3 method:

• render($name, array $parameters = [])- Renders a template
• exists($name)- Checks if the template exists
• supports($name)- 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 theDelegatingEngine class. This classtakes a list of engines and acts just like a normal templating engine. Theonly difference is that it delegates the calls to one of the other engines. Tochoose which one to use for the template, theEngineInterface::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

• Slots Helper
• Creating and Using Templates
• How to Use PHP instead of Twig for Templates
• How to Inject Variables Automatically into all Templates
• How to Embed Asynchronous Content with hinclude.js
• How to Write a custom Twig Extension