Introduction to Twig

1. TWIG
Saturday, 3 November, 12

2. ABOUT ME
Team lead at FreshBooks
Lead Developer of CakePHP
Contributor to Twig
Saturday, 3 November, 12

3. WHAT IS IT
Templating language for PHP.
Uses syntax and ideas from jinja2.
Flexible and extensible at every layer.
Saturday, 3 November, 12

4. BUT PHP IS A
TEMPLATING
LANGUAGE DUMMY
Saturday, 3 November, 12

5. PHP SUCKS FOR TEMPLATING
// In Plain PHP
<?php echo $var; ?> (XSS you lose)
<?php echo htmlspecialchars($var, ENT_QUOTES, ‘UTF-8’); ?>
<?php echo h($var); ?> (sugar for htmlentities)
// In Twig - autoescaping enabled
{{ var }}
Saturday, 3 November, 12

6. BENEFITS OF TWIG
Terse syntax, and sugar.
Automatic HTML escaping.
Sandbox mode, which enables user editable templates.
Ability to create custom DSL’s using application tags, operators
and functions.
Saturday, 3 November, 12

7. PLAIN PHP VS TWIG
Saturday, 3 November, 12

8. CONDITIONALS
// In Plain PHP
<?php if (!empty($var): ?>
...
<?php endif; ?>
// In Twig
{% if var %}
...
{% endif %}
Saturday, 3 November, 12

9. LOOPS
<?php
if (!empty($var):
foreach ((array)$var as $i => $v):
printf(
‘%s : %s’,
htmlspecialchars($i, ENT_QUOTES, ‘UTF-8’),
htmlspecialchars($v, ENT_QUOTES, ‘UTF-8’));
endforeach;
else:
echo ‘No things’;
endif;
Saturday, 3 November, 12

10. LOOPS
{% for i, v in var %}
{{ i }} : {{ v }}
{% else %}
No things
{% endfor %}
Saturday, 3 November, 12

11. LOOPS
{% for user in users if user.active %}
{{ user.name }} : {{ user.email }}
{% else %}
No active users
{% endfor %}
Saturday, 3 November, 12

12. BUT WAIT THERE IS
MORE
Saturday, 3 November, 12

13. AWESOME++
Macros.
Blocks & extending templates.
Saturday, 3 November, 12

14. MACROS
{% macro username(user) %}
<a href=”{{ url({
‘controller’: ‘users’,
‘action’: ‘view’,
user.username) }}”>
<span class=”user-first-name”>
{{ user.first_name }}
</span>
<span> class=”user-last-name”>
{{ user.last_name }}
</span>
</a>
{% endmacro %}
Saturday, 3 November, 12

15. IMPORTING MACROS
// import all the macros
{% import ‘/import/formatting.twig’ as formatting %}
{{ formatting.username(user) }}
// import one macro
{% from ‘/import/formatting.twig’ import username %}
{{ username(user) }}
// import one & alias it.
{% from ‘/import/formatting.twig’ import username as un %}
{{ un(user) }}
Saturday, 3 November, 12

16. INHERITANCE & BLOCKS
Extending views & blocks work hand in hand.
Blocks are like slots or holes in a template, that the child can fill.
Blocks can be used out of order, which is pretty sweet.
Blocks can be imported from other templates, similar to traits.
Saturday, 3 November, 12

17. INHERITANCE
{# layout/base.twig #}
Company X - Official Email template
{% block content ‘Super important’ %}
Copyright 2012
Saturday, 3 November, 12

18. INHERITANCE
{# email/winner.twig #}
{% extend ‘/layout/base.twig’ %}
{% block content %}
To whom it may concern,
You win!
{% endblock %}
Saturday, 3 November, 12

19. INHERITANCE
{# email/winner.twig #}
{% extend ‘/layout/base.twig’ %}
{% block content %}
To whom it may concern,
{{ parent() }} You win!
{% endblock %}
Saturday, 3 November, 12

20. INHERITANCE TIPS
Don’t use {% block %} inside a loop. It doesn’t do what you
want.
You can use {{ block(name) }} to dynamically call blocks.
Saturday, 3 November, 12

21. EXTENDING TWIG
TWIG EXTENSIONS
Saturday, 3 November, 12

22. EXTENDING TWIG
Twig can be extended in several ways.
Filters, Functions, Globals, Tests, Operators, TokenParsers,
NodeVisitors.
You should use extensions to package up your enhancements.
Saturday, 3 November, 12

23. TWIG EXTENSIONS
Saturday, 3 November, 12

24. LOADING EXTENSIONS
$loader = new Twig_Loader_FileSystem (APP . ‘/templates’);
$twig = new Twig_Environment($loader, $options);
$twig->addExtension(new App_Extension_Url());
Saturday, 3 November, 12

25. ENVIRONMENT FACTORY
class AppTwig {
static function loadTemplate($template, $options = array()) {
$loader = new Twig_Loader_FileSystem (APP . ‘/templates’);
$twig = new Twig_Environment($loader, $options);
$twig->addExtension(new App_Extension_Url());
// Load more extensions
return $twig->loadTemplate($template);
}
}
$template = AppTwig::loadTemplate(‘/users/profile.twig’ );
Saturday, 3 November, 12

26. EXTENSION EXAMPLE
<?php
class App_Extension_Url extends Twig_Extension {
public function getName() {
return ‘app.url’;
}
public function getFilters() {
return array(
‘name’ => new Twig_Filter_Method($this, ‘formatName’),
);
}
}
Saturday, 3 November, 12

27. GLOBALS
Can be used to expose application or framework objects.
Great for migrating an older codebase to use Twig.
E.g {{ html.link(...) }}
Saturday, 3 November, 12

28. FUNCTIONS
Global functions added to a template context.
Great for providing shortcuts to application features, like url
generation or built-in PHP functions.
Example {{ form_input(model, ‘name’) }}
Saturday, 3 November, 12

29. FILTERS
Filters are intended for simple formatting functions.
The filtered variable is the first argument to the filter function.
Filters can have additional arguments as well.
Example: {{ invoice.amount|currency(‘CAD’) }}
Saturday, 3 November, 12

30. TESTS
Allow you to implement custom conditional logic. In an
expressive manner with domain objects.
Value being compared is supplied as the first argument. Other
arguments follow.
{% if user is paying %}
{% if number is divisibleby(3) %}
Saturday, 3 November, 12

31. NODE VISITORS
Allows you to visit each node in the Abstract syntax tree.
Applied before template is compiled.
Commonly used for optimizing the AST, or applying
transformations to, or reading data from nodes in the tree.
Saturday, 3 November, 12

32. CUSTOM TAGS
Saturday, 3 November, 12

33. TWIG INTERNALS
LOADER
ENVIRONMENT
Saturday, 3 November, 12

34. TWIG INTERNALS
LOADER
LEXERENVIRONMENT
Saturday, 3 November, 12

35. TWIG INTERNALS
LOADER
LEXERENVIRONMENT
TOKENS
Saturday, 3 November, 12

36. TWIG INTERNALS
LOADER
LEXERENVIRONMENT
TOKENS
PARSER
Saturday, 3 November, 12

37. TWIG INTERNALS
LOADER
LEXERENVIRONMENT
TOKENS
PARSER
NODES
Saturday, 3 November, 12

38. TWIG INTERNALS
LOADER
LEXERENVIRONMENT
TOKENS
PARSER COMPILER
NODES
Saturday, 3 November, 12

39. TWIG INTERNALS
LOADER
LEXERENVIRONMENT
TOKENS
PARSER COMPILER
NODES
PHP CODE
Saturday, 3 November, 12

40. TOKEN PARSERS
Used to implement custom tags or DSL features.
The most complex feature to add.
Each tag is composed of two parts:
TokenParser - parses the tag and validates its syntax.
Node - Added to the AST and compiles the PHP code used
in templates.
Saturday, 3 November, 12

41. TAG EXAMPLE
{% debug %}
{% debug my_var %}
{% debug 2 > 1 %}
Saturday, 3 November, 12

42. TOKEN PARSER
class App_TokenParser_Debug extends Twig_TokenParser {
public function parse(Twig_Token $token) {
$line = $token->getLine();
$expr = null;
if (!$this->parser->getStream()->test( Twig_Token::BLOCK_END_TYPE)) {
$expr = $this->parser->getExpressionParser->parseExpression();
}
$this->parse->getStream()->expect( Twig_Token::BLOCK_END_TYPE);
return new App_Node_Debug($expr, $line, $this->getTag());
}
}
Saturday, 3 November, 12

43. NODE COMPILER
class App_Node_Debug extends Twig_Node {
public function __construct( Twig_Node_Expression $ex, $line, $tag) {
parent::__construct(array(‘expr’ => $ex), $line, $tag);
}
public function compile(Twig_Compiler $compiler) {
$compiler->write(‘if ($this->env->isDebug()) {‘ );
if ($this->getNode(‘expr’) === null) {
// Print all vars.
} else {
$compiler->write(‘var_dump(‘)
->subcompile($this->getNode(‘expr’))
->raw(‘);’);
}
$compiler->write(‘}’);
}
}
Saturday, 3 November, 12

44. OPERATORS
Allow you to add additional boolean operators.
I’ve never used this feature.
Saturday, 3 November, 12

45. DEPLOYING TWIG
Saturday, 3 November, 12

46. TWIG IN PRODUCTION
FreshBooks (the app, not the website).
520+ templates.
Twig templates are used for almost all HTML & E-mail content.
Saturday, 3 November, 12

47. TEMPLATE COMPILATION
TWIG
Saturday, 3 November, 12

48. TEMPLATE COMPILATION
TWIG
PHP
Saturday, 3 November, 12

49. TEMPLATE COMPILATION
TWIG
PHP
HTML
Saturday, 3 November, 12

50. TEMPLATE COMPILATION
TWIG
PHP
HTML
Saved to disk
Saturday, 3 November, 12

51. TEMPLATE COMPILATION
PHP
HTML
Saved to disk
Saturday, 3 November, 12

52. HOW WE DEPLOY
Saturday, 3 November, 12

53. HOW WE DEPLOY
COPY
FILES
Saturday, 3 November, 12

54. HOW WE DEPLOY
COPY
FILES
COMPILE
/ BUILD
Saturday, 3 November, 12

55. HOW WE DEPLOY
COPY
FILES
COMPILE
/ BUILD
SYMLINK
Saturday, 3 November, 12

56. PRECOMPILE SCRIPT
$directory = new RecursiveDirectoryIterator ($argv[0]);
$recurser = new RecursiveIteratorIterator ($directory);
$matcher = new RegexIterator(
$recurser,
'/.*?\.twig$/',
RegexIterator::GET_MATCH);
echo "Compiling Templates" ;
$i = 0;
foreach ($matcher as $file) {
$filename = str_replace($argv[1], '', $file[0]);
AppTwig::loadTemplate('/' . $filename);
echo '.';
$i++;
}
echo "Templates compiled" ;
exit(0);
Saturday, 3 November, 12

57. TWIG C EXTENSION
You can also install ext/twig.
This pushes the most frequently used method
Twig_Template::getAttribute() into C which increases
performance considerably.
The C extension is in the Twig repository.
Saturday, 3 November, 12

58. QUESTIONS?
Saturday, 3 November, 12

59. THANKS
@MARK_STORY
HTTP://MARK-STORY.COM
Saturday, 3 November, 12