diff options
Diffstat (limited to 'vendor/twig/twig/doc/intro.rst')
-rw-r--r-- | vendor/twig/twig/doc/intro.rst | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/vendor/twig/twig/doc/intro.rst b/vendor/twig/twig/doc/intro.rst new file mode 100644 index 00000000..bdcdb8a0 --- /dev/null +++ b/vendor/twig/twig/doc/intro.rst | |||
@@ -0,0 +1,164 @@ | |||
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 | ||