aleph1.co.uk Git - yaffs-website/blob - 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 their own custom tags and filters, and to create their own DSL.
  23
  24 Twig is used by many Open-Source projects like Symfony, Drupal8, eZPublish,
  25 phpBB, Piwik, OroCRM; and many frameworks have support for it as well like
  26 Slim, Yii, Laravel, Codeigniter and Kohana — just to name a few.
  27
  28 Prerequisites
  29 -------------
  30
  31 Twig needs at least **PHP 5.2.7** to run. As of 1.34, the minimum requirement
  32 was bumped to **PHP 5.3.3**.
  33
  34 Installation
  35 ------------
  36
  37 The recommended way to install Twig is via Composer:
  38
  39 .. code-block:: bash
  40
  41     composer require "twig/twig:~1.0"
  42
  43 .. note::
  44
  45     To learn more about the other installation methods, read the
  46     :doc:`installation<installation>` chapter; it also explains how to install
  47     the Twig C extension.
  48
  49 Basic API Usage
  50 ---------------
  51
  52 This section gives you a brief introduction to the PHP API for Twig.
  53
  54 .. code-block:: php
  55
  56     require_once '/path/to/vendor/autoload.php';
  57
  58     $loader = new Twig_Loader_Array(array(
  59         'index' => 'Hello {{ name }}!',
  60     ));
  61     $twig = new Twig_Environment($loader);
  62
  63     echo $twig->render('index', array('name' => 'Fabien'));
  64
  65 Twig uses a loader (``Twig_Loader_Array``) to locate templates, and an
  66 environment (``Twig_Environment``) to store the configuration.
  67
  68 The ``render()`` method loads the template passed as a first argument and
  69 renders it with the variables passed as a second argument.
  70
  71 As templates are generally stored on the filesystem, Twig also comes with a
  72 filesystem loader::
  73
  74     $loader = new Twig_Loader_Filesystem('/path/to/templates');
  75     $twig = new Twig_Environment($loader, array(
  76         'cache' => '/path/to/compilation_cache',
  77     ));
  78
  79     echo $twig->render('index.html', array('name' => 'Fabien'));
  80
  81 .. tip::
  82
  83     If you are not using Composer, use the Twig built-in autoloader::
  84
  85         require_once '/path/to/lib/Twig/Autoloader.php';
  86         Twig_Autoloader::register();