Základní syntaxe Twigu

Potřebujeme znát 3 základní syntaktické konstrukce:

• {{ … }} něco říká, používá se např. pro vykreslení proměnné.
• {% … %} něco dělá a používá se v případě, kdy v šabloně potřebujeme nějakou logiku, například definovat proměnnou, zapsat podmínku nebo třeba importovat jinou šablonu.
• {# … #} něco komentuje.

Příklad na úvod

Všechny zdrojáky najdete v repozitáři na GitHubu.

Twig nainstalujeme pomocí Composeru

composer require twig/twig

Vytvoříme jednoduchý skript, který bude vykreslovat šablonu Resources/views/index.html.twig. Vystačíme si se dvěma třídami:

• Twig_Loader_Filesystem – třída zajišťující načítání šablon. V konstruktoru jednoduše nastavíme cestu ke složce, ve které má šablony hledat.
• Twig_Environment – slouží ke konfiguraci našeho Twig prostředí. Jako první parametr přebírá implementaci Twig_LoaderInterface, která se bude používat pro načítání šablon.  V našem případě je to právě Twig_Loader_Filesystem.

//index.php
require_once __DIR__ . '/vendor/autoload.php';

$loader = new Twig_Loader_Filesystem('Resources/views');
$twig = new Twig_Environment($loader);

echo $twig->render('index.html.twig', ['name' => 'world']);
// Hello world!

Metodou $twig->render() vykreslíme šablonu, kterou definujeme jako první parametr. Druhým parametrem si do šablony můžeme předat pole proměnných. Naše základní šablona pak vypadá takto:

{# index.html.twig #}
Hello {{ name }}!

Přístup k atributům objektu a prvkům pole

Do šablony si můžeme předat i pole nebo objekt, k jehož prvkům (resp. properties) pak můžeme přistupovat unifikovaným způsobem pomocí tečky:

{# index.html.twig #}
My favourite movie: {{ movie1.title }}<br>
My friends favourite movie: {{ movie2.title }}

//index.php
require_once __DIR__ . '/vendor/autoload.php';

class Movie {

 /**
  * @var string
  */
 private $title;

 /**
  * @param string $title
  */
 public function __construct($title) {
  $this->title = $title;
 }

 /**
  * @return string
  */
 public function getTitle() {
  return $this->title;
 }
}

$loader = new Twig_Loader_Filesystem('Resources/views');
$twig = new Twig_Environment($loader);

$movieAsObject = new Movie('Kill Bill');
$movieAsArray = ['title' => 'Matrix']; 

echo $twig->render('index.html.twig', [
 'movie1' => $movieAsObject, 
 'movie2' => $movieAsArray, 
]);
// My favourite movie: Kill Bill
// My friends favourite movie: Matrix

Cykly, podmínky, operátory

Ve Twigu můžeme používat i cykly a podmínky, k dispozici máme navíc i rozsáhlou sadu operátorů, díky kterým je práce se šablonami zase o něco jednodušší. Operátory můžeme rozdělit na

• logické (např. and, or)
• porovnávací/testovací (např. ==, is not, empty nebo matches, pokud chceme používat regulární výrazy)
• a další (např. ~ pro konkatenaci stringů, ternární operátor ?: nebo samozřejmě klasické matematické operátory pro sčítání, odčítání atd.).

Abychom nezůstávali dlouho u teorie, ukažme si jednoduchý příklad použití v kódu:

//index.php
require_once __DIR__ . '/vendor/autoload.php';
class Movie {

 /**
  * @var string
  */
 private $title;

 /**
  * @var string|null
  */
 private $comment;

 /**
  * @param string $title
  * @param string|null $comment
  */
 public function __construct($title, $comment = null) {
  $this->title = $title;
  $this->comment = $comment;
 }

 /**
  * @return string
  */
 public function getTitle() {
  return $this->title;
 }

 /**
  * @return string|null
  */
 public function getComment() {
  return $this->comment;
 }
}

$loader = new Twig_Loader_Filesystem('Resources/views');
$twig = new Twig_Environment($loader);

$movies = [
 new Movie('Reservoir Dogs'),
 new Movie('Jackie Brown'),
 new Movie('Grindhouse'),
 new Movie('Pulp Fiction', 'Oscar for Best Writing'),
 new Movie('Kill Bill'),
];

echo $twig->render('index.html.twig', [
 'movies' => $movies,
]);

{# index.html.twig #}
Quentin Tarantino movies: <br>
<ul>
 {% for movie in movies %}
  <li>
     {{ movie.title }}
     {% if movie.comment is not null %}
        - <i>{{ movie.comment }}</i>
     {% endif %}
  </li>
 {% endfor %}
</ul>

Co ještě Twig umí?

 Filtry a funkce

Filtry nám slouží nejčastěji k formátování zobrazovaných dat. Užitečné filtry jsou např. length, za jehož pomoci zjišťujeme počet prvků v poli, date pro formátování data, number_format pro formátování čísel nebo trim pro odřezání bílých znaků. Filtr aplikujeme jednoduše pomocí svislítka.

{{ movies|length }}

Funkce většinou provádějí nějakou pokročilejší logiku. Jako příklad funkce může posloužit třeba constant() pro vypisování hodnot PHP konstant. Funkci pak voláme přesně tak, jak by programátor očekával:

{{ constant('Component\\Constraint::MAX_VALUE') }}

Další užitečnou funkcí může být date() pro získání aktuálního data, která funguje obdobně jako v PHP.

{{ date(-2days) }}

Seznam všech funkcí a filtrů najdeme v oficiální dokumentaci.

Filtry a funkce si navíc můžeme vytvářet i vlastní, což si popíšeme v příštím díle.

Dědičnost šablon

Další fantastickou vlastností Twigu je možnost tvořit hierarchii šablon pomocí dědičnosti. Díky tomu lze například vytvořit šablonu, která bude sloužit jako kostra pro základní layout, a tu budou ostatní šablony rozšiřovat pomocí přepisování konkrétních bloků. Dědičnost se definuje pomocí tagu extends.

{# base.html.twig #}
<html>
    <head>
        <meta charset="UTF-8">
        <title>Twig - {% block title %}{% endblock %}</title>
    </head>
    <body>
        <div id="menu">
            This is menu
        </div>
        <div id="main_content">
            {% block main_content %}{% endblock %}
        </div>
    </body>
</html>

{# index.html.twig #}
{% extends 'base.html.twig' %}

{% block title %}
    Index page
{% endblock %}

{% block main_content %}
   This is main content
{% endblock %}

Ve výsledku pak uživatel na stránce uvidí toto:

This is menu
This is main content

Escapování

Jak už bylo zmíněno v úvodu, automatické escapování obsahu proměnných je jednou z klíčových vlastností šablonovacích systémů, Twig nevyjímaje. Pokud totiž v šabloně vykresluji proměnnou, je zde vždy riziko, že bude obsahovat znaky, které mohou výsledné HTML rozbít. Navíc pokud na escapování zapomenu, jsem vystaven riziku napadení své aplikace XSS útokem.

Ve Twigu je escapování defaultně zapnuto pro HTML, takže se o něj jako programátor nemusím vůbec starat. Jsou ovšem případy, kdy potřebuji escapování zakázat, např. pokud mám v proměnné naformátovaný obsah článku. V takovém případě můžu použít filtr

{{ article.text|raw }}

Mám taky možnost v konfiguraci escapování zakázat úplně a postarat se o něj ručně, a to hned několika možnými způsoby:

• Pomocí filtru

{{ user.username|escape }}

• nebo zkráceně

{{ user.username|e }}

• nebo pomocí tagu

{% autoescape %}
  {{ user.username }}
{% endautoescape %}

Twig také umožňuje změnit strategii escapování (css, js, url, html_attr), což  lze opět provést buď v konfiguraci

new Twig_Environment($loader, ['autoescape' => 'url']);

nebo při používání filtru

{{ urlAddress|e('url') }}

případně při používání tagu

{% autoescape 'url' %}
   {{ urlAddress }}
{% endautoescape %}

Zase o krok dále

Dnes jsme se dozvěděli,

• že díky používání Twigu máme zajištěno automatické escapování a přehlednější zdrojáky
• že Twig umí spoustu užitečných věcí, jako je třeba dědičnost šablon
• že použití Twigu v naší aplikaci je opravdu hračka

Co nás čeká příště?

V dalším díle se na Twig podíváme ještě podrobněji. Na co se můžete těšit?

• Twig Extensions a integrace Twigu v Symfony,
• používání překladů v šablonách,
• tvorba vlastní funkce a filtru,
• makra,
• maily a další možnosti využití šablon