vendor/twig/twig/doc/intro.rst

   1 Introduction
   2 ============
   3
   4 This is the documentation for Twig, the flexible, fast, and secure template
   5 engine for PHP.
   6
   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.
  11
  12 The key-features are...
  13
  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.
  16
  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.
  20
  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.
  23
  24 Prerequisites
  25 -------------
  26
  27 Twig needs at least **PHP 5.2.4** to run.
  28
  29 Installation
  30 ------------
  31
  32 You have multiple ways to install Twig.
  33
  34 Installing via Composer (recommended)
  35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  36
  37 1. Install composer in your project:
  38
  39 .. code-block:: bash
  40
  41     curl -s http://getcomposer.org/installer | php
  42
  43 2. Create a ``composer.json`` file in your project root:
  44
  45 .. code-block:: javascript
  46
  47     {
  48         "require": {
  49             "twig/twig": "1.*"
  50         }
  51     }
  52
  53 3. Install via composer
  54
  55 .. code-block:: bash
  56
  57     php composer.phar install
  58
  59 .. note::
  60     If you want to learn more about Composer, the ``composer.json`` file syntax
  61     and its usage, you can read the `online documentation`_.
  62
  63 Installing from the tarball release
  64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66 1. Download the most recent tarball from the `download page`_
  67 2. Unpack the tarball
  68 3. Move the files somewhere in your project
  69
  70 Installing the development version
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  72
  73 1. Install Git
  74 2. ``git clone git://github.com/fabpot/Twig.git``
  75
  76 Installing the PEAR package
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78
  79 1. Install PEAR
  80 2. ``pear channel-discover pear.twig-project.org``
  81 3. ``pear install twig/Twig`` (or ``pear install twig/Twig-beta``)
  82
  83
  84 Installing the C extension
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  86
  87 .. versionadded:: 1.4
  88     The C extension was added in Twig 1.4.
  89
  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:
  92
  93 .. code-block:: bash
  94
  95     $ cd ext/twig
  96     $ phpize
  97     $ ./configure
  98     $ make
  99     $ make install
 100
 101 Finally, enable the extension in your ``php.ini`` configuration file:
 102
 103 .. code-block:: ini
 104
 105     extension=twig.so
 106
 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.
 111
 112 .. tip::
 113
 114     On Windows, you can also simply download and install a `pre-built DLL`_.
 115
 116 Basic API Usage
 117 ---------------
 118
 119 This section gives you a brief introduction to the PHP API for Twig.
 120
 121 The first step to use Twig is to register its autoloader::
 122
 123     require_once '/path/to/lib/Twig/Autoloader.php';
 124     Twig_Autoloader::register();
 125
 126 Replace the ``/path/to/lib/`` path with the path you used for Twig
 127 installation.
 128
 129 If you have installed Twig via Composer you can take advantage of Composer's
 130 autoload mechanism by replacing the previous snippet for::
 131
 132     require_once '/path/to/vendor/autoload.php';
 133
 134 .. note::
 135
 136     Twig follows the PEAR convention names for its classes, which means you
 137     can easily integrate Twig classes loading in your own autoloader.
 138
 139 .. code-block:: php
 140
 141     $loader = new Twig_Loader_String();
 142     $twig = new Twig_Environment($loader);
 143
 144     echo $twig->render('Hello {{ name }}!', array('name' => 'Fabien'));
 145
 146 Twig uses a loader (``Twig_Loader_String``) to locate templates, and an
 147 environment (``Twig_Environment``) to store the configuration.
 148
 149 The ``render()`` method loads the template passed as a first argument and
 150 renders it with the variables passed as a second argument.
 151
 152 As templates are generally stored on the filesystem, Twig also comes with a
 153 filesystem loader::
 154
 155     $loader = new Twig_Loader_Filesystem('/path/to/templates');
 156     $twig = new Twig_Environment($loader, array(
 157         'cache' => '/path/to/compilation_cache',
 158     ));
 159
 160     echo $twig->render('index.html', array('name' => 'Fabien'));
 161
 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