twig Getting started with twig


This section provides an overview of what twig is, and why a developer might want to use it.

It should also mention any large subjects within twig, and link out to the related topics. Since the Documentation for twig is new, you may need to create initial versions of those related topics.

Basic API Usage

It can also be installed by downloading the source code and placing it in a directory of your project. However there are many benefits to using composer.

require '/path/to/lib/Twig/Autoloader.php';

$loader = new Twig_Loader_Filesystem('/path/to/templates');

$options = array(
    'strict_variables' => false,
    'debug' => false,
    'cache'=> false

$twig = new Twig_Environment($loader, $options);

When creating a new Twig_Environment instance, you can pass an array of options as the constructor's second argument. Here is a list of the available options:

  • debug (boolean, default false)

When set to true, the generated templates have a __toString() method that you can use to display the generated nodes.

  • charset (string, default utf-8)

The charset used by the templates.

  • base_template_class (string, default Twig_Template)

The base template class to use for generated templates.

  • cache (string or false, default false)

An absolute path where to store the compiled templates, or false to disable caching (which is the default).

  • auto_reload (boolean, default inherited from debug)

When developing with Twig, it's useful to recompile the template whenever the source code changes. If you don't provide a value for the auto_reload option, it will be determined automatically based on the debug value.

  • strict_variables (boolean, default false)

If set to false, Twig will silently ignore invalid variables (variables and or attributes/methods that do not exist) and replace them with a null value. When set to true, Twig throws an exception instead.

  • autoescape (string or boolean, defaulttrue)

If set to true, HTML auto-escaping will be enabled by default for all templates.

As of Twig 1.8, you can set the escaping strategy to use (html, js, false to disable).

As of Twig 1.9, you can set the escaping strategy to use (css, url, html_attr, or a PHP callback that takes the template "filename" and must return the escaping strategy to use -- the callback cannot be a function name to avoid collision with built-in escaping strategies).

As of Twig 1.17, the filename escaping strategy determines the escaping strategy to use for a template based on the template filename extension (this strategy does not incur any overhead at runtime as auto-escaping is done at compilation time.)

  • optimizations (integer, default -1)

A flag that indicates which optimizations to apply:
set to -1 to enabled all optimalizations
set o 0 to disable all optimalitazations

Official Twig Installation Guide

A Twig PHP extension (written in C) can also be compiled and installed, and the PHP package will automatically take advantage of that for optimizing some common routines.

What is Twig?

Twig is a templating language that compiles to optimized PHP code. It is primarily used for outputting HTML, but can also be used to output any other text-based format. It is a standalone component that can be easily integrated into any PHP project.

It provides many excellent features:

  • Autoescaping for HTML (helps to prevent XSS)
  • Syntax designed with templating in mind (based on Django templates)
  • Template inheritance
  • Macros

Official Twig Templating Documentation

Example of Twig's syntax:

{% extends "base.html" %}

{% block sidebar %}
  {{ parent() }}
  <span>Sidebar content specific to this page</span>
{% endblock sidebar %}

{% block body %}
  <p>Select an item:</p>
    {% for item in list %}
      <li><a href="/items/{{ }}">{{ }}</a>
    {% else %}
      <li>No items yet.
    {% endfor %}
{% endblock body %}


If you have any exposure to other text-based template languages, such as Smarty, Django, or Jinja, you should feel right at home with Twig. It's both designer and developer friendly by sticking to PHP's principles and adding functionality useful for templating environments.

The key-features are...

  • Fast: Twig compiles templates down to plain optimized PHP code. The overhead compared to regular PHP code was reduced to the very minimum.
  • Secure: Twig has a sandbox mode to evaluate untrusted template code. This allows Twig to be used as a template language for applications where users may modify the template design.
  • Flexible: Twig is powered by a flexible lexer and parser. This allows the developer to define their own custom tags and filters, and to create their own DSL.

Twig is used by many Open-Source projects like Symfony, Drupal, eZPublish and many frameworks have support for it as well like Slim, Yii, Laravel, Codeigniter,silex and Kohana — just to name a few.


The recommended way to install Twig is via Composer:

For php 5.x users

composer require "twig/twig:~1.0"

For php 7.x users

composer require "twig/twig:~2.0"