doc/intro.rst
a855b189
 Introduction
 ============
 
 This is the documentation for Twig, the flexible, fast, and secure template
 engine for PHP.
 
 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
e81e6981
   developer to define their own custom tags and filters, and to create their own DSL.
a855b189
 
e375c9c5
 Twig is used by many Open-Source projects like Symfony, Drupal8, eZPublish,
e81e6981
 phpBB, Piwik, OroCRM; and many frameworks have support for it as well like
 Slim, Yii, Laravel, Codeigniter and Kohana — just to name a few.
e375c9c5
 
a855b189
 Prerequisites
 -------------
 
747d7bea
 Twig needs at least **PHP 7.0.0** to run.
a855b189
 
 Installation
 ------------
 
a0efdc98
 The recommended way to install Twig is via Composer:
e765183c
 
 .. code-block:: bash
7153ff6c
 
8a62689d
     composer require "twig/twig:^2.0"
7153ff6c
 
a855b189
 Basic API Usage
 ---------------
 
 This section gives you a brief introduction to the PHP API for Twig.
 
dd1ead23
 .. code-block:: php
5c805a1b
 
550503ec
     require_once '/path/to/vendor/autoload.php';
5c805a1b
 
3632a46e
     $loader = new \Twig\Loader\ArrayLoader([
d12f7afb
         'index' => 'Hello {{ name }}!',
a2c42534
     ]);
3632a46e
     $twig = new \Twig\Environment($loader);
a855b189
 
a2c42534
     echo $twig->render('index', ['name' => 'Fabien']);
a855b189
 
3632a46e
 Twig uses a loader (``\Twig\Loader\ArrayLoader``) to locate templates, and an
 environment (``\Twig\Environment``) to store the configuration.
a855b189
 
d65366e7
 The ``render()`` method loads the template passed as a first argument and
 renders it with the variables passed as a second argument.
a855b189
 
d65366e7
 As templates are generally stored on the filesystem, Twig also comes with a
 filesystem loader::
a855b189
 
3632a46e
     $loader = new \Twig\Loader\FilesystemLoader('/path/to/templates');
     $twig = new \Twig\Environment($loader, [
3697ef4a
         'cache' => '/path/to/compilation_cache',
a2c42534
     ]);
a855b189
 
a2c42534
     echo $twig->render('index.html', ['name' => 'Fabien']);