4 Twig is very extensible and you can easily hack it. Keep in mind that you
5 should probably try to create an extension before hacking the core, as most
6 features and enhancements can be handled with extensions. This chapter is also
7 useful for people who want to understand how Twig works under the hood.
12 The rendering of a Twig template can be summarized into four key steps:
14 * **Load** the template: If the template is already compiled, load it and go
15 to the *evaluation* step, otherwise:
17 * First, the **lexer** tokenizes the template source code into small pieces
18 for easier processing;
19 * Then, the **parser** converts the token stream into a meaningful tree
20 of nodes (the Abstract Syntax Tree);
21 * Eventually, the *compiler* transforms the AST into PHP code.
23 * **Evaluate** the template: It basically means calling the ``display()``
24 method of the compiled template and passing it the context.
29 The lexer tokenizes a template source code into a token stream (each token is
30 an instance of ``Twig_Token``, and the stream is an instance of
31 ``Twig_TokenStream``). The default lexer recognizes 13 different token types:
33 * ``Twig_Token::BLOCK_START_TYPE``, ``Twig_Token::BLOCK_END_TYPE``: Delimiters for blocks (``{% %}``)
34 * ``Twig_Token::VAR_START_TYPE``, ``Twig_Token::VAR_END_TYPE``: Delimiters for variables (``{{ }}``)
35 * ``Twig_Token::TEXT_TYPE``: A text outside an expression;
36 * ``Twig_Token::NAME_TYPE``: A name in an expression;
37 * ``Twig_Token::NUMBER_TYPE``: A number in an expression;
38 * ``Twig_Token::STRING_TYPE``: A string in an expression;
39 * ``Twig_Token::OPERATOR_TYPE``: An operator;
40 * ``Twig_Token::PUNCTUATION_TYPE``: A punctuation sign;
41 * ``Twig_Token::INTERPOLATION_START_TYPE``, ``Twig_Token::INTERPOLATION_END_TYPE`` (as of Twig 1.5): Delimiters for string interpolation;
42 * ``Twig_Token::EOF_TYPE``: Ends of template.
44 You can manually convert a source code into a token stream by calling the
45 ``tokenize()`` method of an environment::
47 $stream = $twig->tokenize(new Twig_Source($source, $identifier));
49 .. versionadded:: 1.27
50 ``Twig_Source`` was introduced in version 1.27, pass the source and the
51 identifier directly on previous versions.
53 As the stream has a ``__toString()`` method, you can have a textual
54 representation of it by echoing the object::
58 Here is the output for the ``Hello {{ name }}`` template:
70 The default lexer (``Twig_Lexer``) can be changed by calling
71 the ``setLexer()`` method::
73 $twig->setLexer($lexer);
78 The parser converts the token stream into an AST (Abstract Syntax Tree), or a
79 node tree (an instance of ``Twig_Node_Module``). The core extension defines
80 the basic nodes like: ``for``, ``if``, ... and the expression nodes.
82 You can manually convert a token stream into a node tree by calling the
83 ``parse()`` method of an environment::
85 $nodes = $twig->parse($stream);
87 Echoing the node object gives you a nice representation of the tree::
91 Here is the output for the ``Hello {{ name }}`` template:
96 Twig_Node_Text(Hello )
98 Twig_Node_Expression_Name(name)
104 The default parser (``Twig_TokenParser``) can be changed by calling the
105 ``setParser()`` method::
107 $twig->setParser($parser);
112 The last step is done by the compiler. It takes a node tree as an input and
113 generates PHP code usable for runtime execution of the template.
115 You can manually compile a node tree to PHP code with the ``compile()`` method
118 $php = $twig->compile($nodes);
120 The generated template for a ``Hello {{ name }}`` template reads as follows
121 (the actual output can differ depending on the version of Twig you are
124 /* Hello {{ name }} */
125 class __TwigTemplate_1121b6f109fe93ebe8c6e22e3712bceb extends Twig_Template
127 protected function doDisplay(array $context, array $blocks = array())
131 echo twig_escape_filter($this->env, (isset($context["name"]) ? $context["name"] : null), "html", null, true);
139 The default compiler (``Twig_Compiler``) can be changed by calling the
140 ``setCompiler()`` method::
142 $twig->setCompiler($compiler);