Templating with Twig

Writing PHP and HTML together is sooo 1998 – which is why Symfony uses the Twig templating language by default. This means instead of writing ugly code like this:

… we can use this:

Much nicer. Twig not only allows us to use a “friendlier” syntax when writing our presentation layer code, but it also provides some powerful features that make it more than just lipstick for your code.

But where do Twig templates fit in Symfony?

If you’ve poked around the Symfony folder structure (or created some Symfony projects) you’ve probably come across Twig templates already. They end in a “.twig” extension, and are commonly found in these folders:

// Application-wide templates
app/Resources/views

// Bundle-specific templates
src/MyCompany/BlogBundle/Resources/views

But where do they fit into the standard flow of control in the Symfony framework? Well, let’s look inside a standard controller.

You can see the template being invoked in the return statement, where two parameters are supplied. The first is the logical name of the template, the second is the set of parameters to pass-on to the template. These parameters are then used to dynamically modify the output of the template. Next we’ll check out the tools that Twig provides for us to make writing dynamic output easy.

Using Twig Tags

Twig uses braces to separate standard text (which should simply appear in the output as-is) from code (which should provide dynamic behaviour). There are three “kinds” of braces:

{{  }} ... used to "print" variables to the output
{%  %} ... used for control structures
{#  #} ... used for comments.

With this in mind, let’s have a look at a bigger example of a Twig template…

Modifying output with Filters

Because you have such a keen eye, you probably noticed something strange about the way variables are being rendered in the snippet above. Namely this:

{{ title|raw }}

We know that the variable name is “title” and that this is passed from the controller. The token after the pipe (|) character is called a filter, and is used to modify the output of the variable before inserting it into the template. Twig provides us with a range of filters for different purposes such as output escaping, capitalisation, encoding and sorting. You can learn about all the available Twig filters here.

Blocks and Inheritance

One of the most powerful features of Twig is the use of “blocks”. Blocks enable us to define sections of the template that can be overwritten if redefined at a later point. The power of this isn’t immediately evident when dealing with single templates, but can is easy to illustrate when we consider Twig’s inheritance mechanism.

Parent template

Child template

What we can see in the two code snippets above is that the child template is adding the content from the parent but before the template is rendered, any blocks that were redefined in the child overwrite those in the parent. This is an important distinction to make, as we can also “include” other templates, as illustrated below:

So what’s the difference between extending and including? The key difference is that when extending a base template, we can change the content in the base template. When including another template we cannot overwrite any content in the parent.

Automatic template selection

At the start of the lesson we had a look at a possible way that we could use to tell a controller which template to use. We did make things a little bit more difficult for ourselves in the suggested implementation of the method, as there’s an easier way to use templates with controllers, provided we stick to Symfony’s standard template naming convention. The way we can implement this (if using PHP annotations) is illustrated below.

When using the @Template annotation, Symfony will look in the src/Namespace/Bundle/Resources/view/ folder for a template that matches the name of the action and use the return value from the function as the variable scope for the template. In the case above, the template used would be:

/src/MyCompany/BlogBundle/Resources/views/view.html.twig

The end

That’s a very test-drive of the Twig templating language. The library itself is very comprehensive and includes some great features not even touched on in this brief examination. Learn more about Twig by checking out the official online documentation.