]>
Commit | Line | Data |
---|---|---|
4f5b44bd NL |
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 |