4 This is the documentation for Twig, the flexible, fast, and secure template
7 If you have any exposure to other text-based template languages, such as
8 Smarty, Django, or Jinja, you should feel right at home with Twig. It's both
9 designer and developer friendly by sticking to PHP's principles and adding
10 functionality useful for templating environments.
12 The key-features are...
14 * *Fast*: Twig compiles templates down to plain optimized PHP code. The
15 overhead compared to regular PHP code was reduced to the very minimum.
17 * *Secure*: Twig has a sandbox mode to evaluate untrusted template code. This
18 allows Twig to be used as a template language for applications where users
19 may modify the template design.
21 * *Flexible*: Twig is powered by a flexible lexer and parser. This allows the
22 developer to define its own custom tags and filters, and create its own DSL.
27 Twig needs at least **PHP 5.2.4** to run.
32 You have multiple ways to install Twig.
34 Installing via Composer (recommended)
35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37 1. Install composer in your project:
41 curl -s http://getcomposer.org/installer | php
43 2. Create a ``composer.json`` file in your project root:
45 .. code-block:: javascript
53 3. Install via composer
57 php composer.phar install
60 If you want to learn more about Composer, the ``composer.json`` file syntax
61 and its usage, you can read the `online documentation`_.
63 Installing from the tarball release
64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66 1. Download the most recent tarball from the `download page`_
68 3. Move the files somewhere in your project
70 Installing the development version
71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
74 2. ``git clone git://github.com/fabpot/Twig.git``
76 Installing the PEAR package
77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
80 2. ``pear channel-discover pear.twig-project.org``
81 3. ``pear install twig/Twig`` (or ``pear install twig/Twig-beta``)
84 Installing the C extension
85 ~~~~~~~~~~~~~~~~~~~~~~~~~~
88 The C extension was added in Twig 1.4.
90 Twig comes with a C extension that enhances the performance of the Twig
91 runtime engine. You can install it like any other PHP extension:
101 Finally, enable the extension in your ``php.ini`` configuration file:
107 And from now on, Twig will automatically compile your templates to take
108 advantage of the C extension. Note that this extension does not replace the
109 PHP code but only provides an optimized version of the
110 ``Twig_Template::getAttribute()`` method.
114 On Windows, you can also simply download and install a `pre-built DLL`_.
119 This section gives you a brief introduction to the PHP API for Twig.
121 The first step to use Twig is to register its autoloader::
123 require_once '/path/to/lib/Twig/Autoloader.php';
124 Twig_Autoloader::register();
126 Replace the ``/path/to/lib/`` path with the path you used for Twig
129 If you have installed Twig via Composer you can take advantage of Composer's
130 autoload mechanism by replacing the previous snippet for::
132 require_once '/path/to/vendor/autoload.php';
136 Twig follows the PEAR convention names for its classes, which means you
137 can easily integrate Twig classes loading in your own autoloader.
141 $loader = new Twig_Loader_String();
142 $twig = new Twig_Environment($loader);
144 echo $twig->render('Hello {{ name }}!', array('name' => 'Fabien'));
146 Twig uses a loader (``Twig_Loader_String``) to locate templates, and an
147 environment (``Twig_Environment``) to store the configuration.
149 The ``render()`` method loads the template passed as a first argument and
150 renders it with the variables passed as a second argument.
152 As templates are generally stored on the filesystem, Twig also comes with a
155 $loader = new Twig_Loader_Filesystem('/path/to/templates');
156 $twig = new Twig_Environment($loader, array(
157 'cache' => '/path/to/compilation_cache',
160 echo $twig->render('index.html', array('name' => 'Fabien'));
162 .. _`download page`: https://github.com/fabpot/Twig/tags
163 .. _`online documentation`: http://getcomposer.org/doc
164 .. _`pre-built DLL`: https://github.com/stealth35/stealth35.github.com/downloads