1Introduction
2============
3
4Welcome to the documentation for Twig, the flexible, fast, and secure template
5engine for PHP.
6
7Twig is both designer and developer friendly by sticking to PHP's principles and
8adding functionality useful for templating environments.
9
10The key-features are...
11
12* *Fast*: Twig compiles templates down to plain optimized PHP code. The
13  overhead compared to regular PHP code was reduced to the very minimum.
14
15* *Secure*: Twig has a sandbox mode to evaluate untrusted template code. This
16  allows Twig to be used as a template language for applications where users
17  may modify the template design.
18
19* *Flexible*: Twig is powered by a flexible lexer and parser. This allows the
20  developer to define their own custom tags and filters, and to create their own DSL.
21
22Twig is used by many Open-Source projects like Symfony, Drupal8, eZPublish,
23phpBB, Matomo, OroCRM; and many frameworks have support for it as well like
24Slim, Yii, Laravel, and Codeigniter — just to name a few.
25
26.. admonition:: Screencast
27
28    Like to learn from video tutorials? Check out the `SymfonyCasts Twig Tutorial`_!
29
30Prerequisites
31-------------
32
33Twig 2.x needs at least **PHP 7.2.5** to run.
34
35Installation
36------------
37
38The recommended way to install Twig is via Composer:
39
40.. code-block:: bash
41
42    composer require "twig/twig:^2.0"
43
44Basic API Usage
45---------------
46
47This section gives you a brief introduction to the PHP API for Twig::
48
49    require_once '/path/to/vendor/autoload.php';
50
51    $loader = new \Twig\Loader\ArrayLoader([
52        'index' => 'Hello {{ name }}!',
53    ]);
54    $twig = new \Twig\Environment($loader);
55
56    echo $twig->render('index', ['name' => 'Fabien']);
57
58Twig uses a loader (``\Twig\Loader\ArrayLoader``) to locate templates, and an
59environment (``\Twig\Environment``) to store its configuration.
60
61The ``render()`` method loads the template passed as a first argument and
62renders it with the variables passed as a second argument.
63
64As templates are generally stored on the filesystem, Twig also comes with a
65filesystem loader::
66
67    $loader = new \Twig\Loader\FilesystemLoader('/path/to/templates');
68    $twig = new \Twig\Environment($loader, [
69        'cache' => '/path/to/compilation_cache',
70    ]);
71
72    echo $twig->render('index.html', ['name' => 'Fabien']);
73
74.. _`SymfonyCasts Twig Tutorial`: https://symfonycasts.com/screencast/twig
75