Separate your application’s logic from its views with the flexible template engine from the creator of Symfony

Branching out with Twig



Stand up if you’ve never used the amazing PHP construct include and/or require to assemble the layout of a website… I bet you’re all still sat down. Me too. Using PHP as a template engine is fine and works well while you’re building very small websites with very few requirements. But what if you need more flexibility? What about replacing parts of your layout on demand? What if you want to dynamically include other parts into the layout? Yes, all of this stuff is possible with raw PHP too, but why reinvent the wheel when you can rely on a fast, secure and flexible product?

I am, of course, referring to Twig. In this article I’ll show you what it is and how to use it to simplify your work.

What is Twig?

Twig is a template engine for PHP that has all the major features you may need in your projects. It was created by Fabien Potencier, the developer behind the Symfony framework and it’s released under the new BSD license, so it’s completely free to use. That considered, you should not be surprised by the fact that Twig is the Symfony framework’s template engine of choice. Its requirements are so basic that you may think it can run everywhere. In fact, Twig only needs a version of PHP greater than or equal to 5.2.4. If you’ve ever used Smarty, you’ll see a lot of similarities and will be able to start using it very quickly.

The library has been built with several optimizations in mind, specifically performance. When a template is required, Twig parses it and then outputs the result. However, you can speed up the whole process by caching the compiled version in the form of plan PHP files to reduce the overhead (compared to raw PHP) to a minimum. In addition, the framework is extensible, meaning that in case something you need is missing, you can create your own language constructs. In summary, Twig is a reliable, well documented, completely unit tested and mature enough framework to be safely used in your next project.

Now that you know what Twig is, let’s see how you can install it.

Installing Twig

One of the thing I appreciate is the wide range of possibilities to install Twig. The most common and recommended way is via Composer. The first step is to add it to your project’s dependencies as shown below:

"require": {
   "twig/twig": "1.*"

and then run the update command:

php composer.phar update

In case you were not using Composer in your project, you have to use the install command instead:

php composer.phar install

An alternative method to obtain Twig is via PEAR, typing the following commands:

pear channel-discover
pear install twig/Twig

You can obtain Twig in many other ways but I’ll present just another one, the simplest one: downloading the files from the download page of the project on GitHub. Grab the last release (1.13.2 at the time of writing), extract the files from the archive and put them into your project’s folder.

How to create a Twig template

Before delving into the PHP code needed to load and pass data to your Twig templates, it’s important to understand how a template is built. The first fact you need to know is that while Twig templates do not require a specific file extension, you’ll usually see the use of .twig. Many IDEs that have support for Twig will correctly highlight the syntax of your template (for example PHPStorm) if you use the .twig extension, though. To keep it as simple as possible, I’ll show an example of a HTML page, but remember that you can use this framework to output XML as well as other text-based formats.

A template in Twig is composed of variables, expressions and tags. The former are evaluated at the same time as the template, while the latter give you tools to control the template (for example using if and for). The presented components can be used with two types of delimiters: {% %}, used to execute statements, and {{ }}, used to print the variable or the expression contained. Just like every real HTML or XML page, Twig templates can contain comments that are written in this way: {# This is your comment #}. Before we go any further, let’s see some examples:

{# I'm a comment and these are some examples #}

{# Evaluates the variable bookTitle and print the result inside an h1  #}

{{ bookTitle }}

{# Evaluates the expression composed of the authorName variable and the string " De Rosa", concatenated by the "~" character #}

{{ authorName ~ " De Rosa" }}

{# Evaluates the variable count and change the resulting template accordingly #} {% if count < 1000 %}

This is a good book

{% else %}

This is a best seller

{% endif %}

In the above example, the value of the variables was ideally sent by the PHP page that required the template. In certain situations, you may need to set the value of a variable inside the template itself. To perform this task you can use the set tag like shown below:

{# Set the value of the variable name #}
{% set name = 'Aurelio De Rosa' %}
{# Print the value #}
{{ name }}

Please note that mixing business logic and views isn’t a good practice. Therefore, you should limit the use of set to those cases where it’s strictly required by a view-only scope. For example, this may be useful if you’re using the I18N internationalisation extension and want to apply a filter (more on this in a next section) to the string you want to translate.

In the code above I showed the use of simple variables which can store numbers, strings and similar. In Twig, as you might expect, you can also deal with array and objects. To use their values, you’ve to use a JavaScript-like syntax, therefore you can access a property using the dot operator (for example obj.prop) or using the square brackets (for example obj['prop']). Keep in mind that the previous methods can be used when an attribute contains a Twig’s special characters like the hyphen, that is interpreted as the minus operator. In these cases, you have to use the attribute() function like this: attribute(obj, 'prop').


So far, you’ve seen how to use variables and expressions, so it’s time to delve into the second concept of Twig templates: tags. As said, they give you control over the template and how it acts. In the previous examples you’ve already seen a couple of tags, that is set and if. Now, what if you want to print a list of items, for example a list of ingredients of a recipe? This is exactly where the for tag comes into play. To perform this task, you can do something like:


    {% for ingredient in ingredients %}
  • {{ ingredient }}
  • {% endfor %}

Another key tag is block, which allows you to declare a named „section“ of your code that can be overridden by a child template in the future. Before showing you an example, it’s important to introduce the last two tags I’ll explain in this article: include and extend.

The include tag is used to include a template into another one just like the PHP include construct. For example, you can put some tags into a file called meta.twig and then have a larger template called layout.twig that includes it. So, in this example the meta.twig file might look like this:

This is then included in the layout template:

      {% include "meta.twig" %}

The extend tag is used to inherit from a parent template and, eventually, overrides some blocks. To see it in action, the best example is to think to a general layout declaration overridden by the template of a specific page. So, let’s say you have a layout.twig template that has the general structure of your website and an about.twig file that has the code and text of your page. This is the typical situation where you’ll use the extend tag. Let’s see an example.

A simple layout file can resemble this:

      {% block pageTitle %}{% endblock %}

Aurelio De Rosa's website

{% block content %}{% endblock %}

Then you can have the about page extending the previous code and injecting the actual content inside the content and the pageTitle blocks:

{% extend "layout.twig" %}

{% block pageTitle %}About{% endblock %}

{% block content %}

Aurelio De Rosa is an Italian web developer who loves new technologies.

{% endblock %}

The framework has other tags that can help you in building your templates, but presenting them all is outside the scope of this article. However, you can find them all in the Twig tags page.


You probably find yourself often modifying variables in a PHP page using functions – for example, escaping HTML characters or converting a sentence to title case. Doing it in the controllers (or in the page if you aren’t adopting an MVC pattern) isn’t a really good practice, because if the same controller is used for other purposes you may need not to apply those functions. The best place to apply those filters is in the view – and luckily Twig knows this, providing you with a bunch of them. Filters are separated from the variable by a pipe symbol (|) and may have optional arguments closed between two brackets. In addition, you can apply multiple filters by chaining them. Recalling the example I outlined, this is a snippet that takes a variable called bookTitle, escapes HTML characters and capitalizes the first letter of each word:

{{ bookTitle|escape|title }}

An example of filter that accepts a parameter is date, to format a date into a given format. It accepts a strings that is compliant with the format supported by the strtotime() function, a DateTime instance, or a DateInterval instance. For instance, to display the current year into a copyright notice you can use the code shown by the example below:

Copyright © Aurelio De Rosa 2010 - {{ "now"|date("Y") }}

Please, note the use of the string „now“ to evaluate the current date and time and the „Y“ parameter to print only the year.

These are just few examples of what you can do. A list of all the filters available can be found in the Twig filters page.

How to load and show a template

So far, you’ve seen how to build a layout, but you’re not yet able to use it to show to the user of your website. Before showing you the code, it’s important to know a little more about the classes included in the library. Twig uses a central class called Twig_Environment where you’ll set the configuration and add the extensions of your project. This is also the object you’ll use to load the templates from the filesystem (or other locations) using the appropriate loader called Twig_Loader_Filesystem. The Twig_Environment constructor accepts two arguments: the first is the loader (for example an instance of Twig_Loader_Filesystem), and the second is an array of options to configure Twig. Some of the options you can set are: cache, to set the path where the compiled PHP files will be stored, autoreload, a boolean to recompile the template whenever the source code changes, and strict_variables, a boolean to ignore invalid or not existent variables, attributes, and methods, replacing them with a null value.

Now that you have an idea of how you can initialize Twig, let’s see some code. The first thing to do to use its classes, is to load the library. If you installed Twig via Composer as suggested in the introduction, this is done using this simple line of code:

require_once '/vendor/autoload.php';
$twig = new Twig_Environment(
  new Twig_Loader_Filesystem('templates/'), array(
      'cache' => 'cache/twig/',
      'auto_reload' => true,
      'strict_variables' => true

The last step is to load the template and then render it, passing in the required variables. To load a template you have to call the loadTemplate() method and pass the path of the template as a parameter. This method returns a Twig_Template instance that you can use to call the render() method, which accepts as a parameter an array containing a set of key-values. In this array, the keys have the same names as those used in your template and the values, are, well…the values to display. Here’s an example of those classes in action:

$template = $twig->loadTemplate('about.twig');
echo $template->render(array('bookTitle' => 'Instant jQuery Selectors', 'bookAuthor' => 'Aurelio De Rosa'));

You can also pass two parameters to the render() method to load the template and pass the variables in one line of code, as shown below:

echo $twig->render('about.twig', array('bookTitle' => 'Instant jQuery Selectors', 'bookAuthor' => 'Aurelio De Rosa'));

Alternatively, you can also use the display() method, that acts as a shortcut of echo $twig->render(...);, to output the template directly, like so:

$twig->display('about.twig', array('bookTitle' => 'Instant jQuery Selectors', 'bookAuthor' => 'Aurelio De Rosa'));

The framework has a lot of other classes and methods not covered here which you can study in the official documentation. However, with the examples described in this section you’re able to start using it right now.


In this article we discovered what Twig is and its basic components. Throughout it, we uncovered the key features of the framework, like variables, tags, and filters, and also studied several examples that should help using it easily in your next projects. Keep in mind that the library has also some important extensions not described here, like the I18N and Intl, which are very useful if you’re developing a multilingual project. With this last hint, the article is over. I hope you enjoyed it and that thanks to it you’ll consider using Twig or another of the available template frameworks.

Aurelio De Rosa is an Italian web and app developer with more than 5 years‘ experience programming for the web using HTML5, CSS3, JavaScript and PHP. He mainly uses the LAMP stack and frameworks like jQuery, jQuery Mobile, and Cordova (PhoneGap) but his interests also include web security, web accessibility, SEO, WordPress and everything he can put his hands on. In the little spare time left, he contributes to the open source community writing libraries for PHP as well as jQuery plugins. Currently he’s self-employed working with the cited technologies. He’s also a regular blogger for several networks (SitePoint, Tuts+, FlippinAwesome) where he writes articles about the topics he usually works with and more.

Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

- Gib Deinen Standort ein -
- or -