Twig

Introduccin o Requisitos previos

o o

Instalando Uso bsico de la API

Twig para diseadores de plantillas

o o o o o o o o o o o o o o o o

Sinopsis Integrando con IDEs Variables Filtros Funciones Argumentos nombrados Estructuras de control Comentarios Incluyendo otras plantillas Herencia en plantillas Escapando HTML Escapando Macros Expresiones Controlando el espacio en blanco Extendiendo

Twig para desarrolladores

o o

Fundamentos Opciones del entorno

o o o o

Cargadores Usando extensiones Extensiones incorporadas Excepciones

Extendiendo Twig
o o o o o o o o

Globales Filtros Funciones Pruebas Etiquetas Creando una extensin Sobrecargando Probando una extensin

Twig por dentro

o o o o

Cmo funciona Twig? El analizador lxico El analizador sintctico El compilador

Recetas
o o o o o o o

Haciendo un diseo condicional Haciendo una inclusin dinmica Sustituyendo una plantilla que adems se extiende a s misma Personalizando la sintaxis Usando propiedades dinmicas de objetos Accediendo al contexto del padre en bucles anidados Definiendo al vuelo funciones y filtros indefinidos

o o

Validando la sintaxis de la plantilla Actualizando plantillas modificadas cuando APC est habilitado yapc.stat=0 Reutilizando el estado de un visitante de nodo Usando el nombre de la plantilla para determinar la estrategia de escape predeterminada Usando una base de datos para almacenar plantillas Usando diferentes fuentes de plantillas

o o

o o

Estndares de codificacin Etiquetas

o o o o o o o o o o o o o o o o o for if macro filter set extends block include import from use spaceless autoescape verbatim flush do sandbox

embed

Filtros
o o o o o o o o o o o o o o o o o o o o o o o o date date_modify format replace number_format url_encode json_encode convert_encoding title capitalize nl2br upper lower striptags join split reverse abs length sort default keys escape raw

o o o

merge slice trim

Funciones
o o o o o o o o o o o range cycle constant random attribute block parent dump date template_from_string include

Probando
o o o o o o o o o divisibleby null even odd sameas constant defined empty iterable

Caractersticas depreciadas

o o o o o o o

Analizadores de segmentos Extendiendo PEAR Filtros Funciones Pruebas Interfaces

Introduccin
Esta es la documentacin de Twig, el flexible, rpido y seguro motor de plantillas para PHP. Si has estado expuesto a otros lenguajes de plantilla basados en texto, tal comoSmarty, Django o Jinja, debes sentirte como en casa con Twig. Es a la vez, un amigable ambiente para el diseador y desarrollador apegado a los principios dePHP, aadiendo til funcionalidad a los entornos de plantillas. Las caractersticas clave son...

Rpido: Twig compila las plantillas hasta cdigo PHP regular optimizado. El costo general en comparacin con cdigo PHP regular se ha reducido al mnimo. Seguro: Twig tiene un modo de recinto de seguridad para evaluar el cdigo de plantilla que no es confiable. Esto te permite utilizar Twig como un lenguaje de plantillas para aplicaciones donde los usuarios pueden modificar el diseo de la plantilla.

Flexible: Twig es alimentado por flexibles analizadores lxico y sintctico. Esto permite al desarrollador definir sus propias etiquetas y filtros personalizados, y crear su propio DSL.

Requisitos previos
Twig necesita por lo menos PHP 5.2.4 para funcionar.

Instalando
Tienes varias formas de instalar Twig. Si no ests seguro qu hacer, descarga el archivo comprimido (tarball).

Instalando la versin comprimida

1. Descarga el archivo comprimido ms reciente desde la pgina de descarga 2. Descomprime el archivo 3. Mueve los archivos a algn lugar en tu proyecto

Instalando la versin de desarrollo

1. Instala desde Subversin o Git 2. Para Git:
3. git clone git://github.com/fabpot/Twig.git

4. Para Subversin:
5. svn co http://svn.twig-project.org/trunk/ twig

Instalando el paquete PEAR

1. Instala PEAR 2. pear channel-discover pear.twig-project.org 3. pear install twig/Twig (o pear install twig/Twig-beta)

Instalando va Composer
1. Instala composer en tu proyecto:
curl -s http://getcomposer.org/installer | php

2. Crea un archivo composer.json en el directorio raz de tu proyecto:

{

"require": { "twig/twig": "1.*" } }

3. Instala va composer
php composer.phar install

Nota
Si quieres aprender ms sobre Composer, la sintaxis del archivo composer.json y su uso, puedes leer la documentacin en lnea.

Instalando la extensin C
Nuevo en la versin 1.4: La extensin C se aadi en Twig 1.4. Twig viene con una extensin C que mejora el rendimiento del motor Twig en tiempo de ejecucin. La puedes instalar como cualquier otra extensin de PHP:
$ cd ext/twig $ phpize $ ./configure $ make $ make install

Por ltimo, activa la extensin en tu archivo de configuracin php.ini:

extension=twig.so

Y a partir de ahora, Twig compilar automticamente tus plantillas para tomar ventaja de la extensin C. Ten en cuenta que esta extensin no sustituye el cdigoPHP, solamente proporciona una versin optimizada del mtodoTwig_Template::getAttribute().

Truco
En Windows tambin, puedes simplemente descargar e instalar una extensin DLL preconstruida.

Uso bsico de la API

Esta seccin te ofrece una breve introduccin a la API PHP de Twig. El primer paso para utilizar Twig es registrar su cargador automtico:
require_once '/ruta/a/lib/Twig/Autoloader.php'; Twig_Autoloader::register();

Sustituye /ruta/a/lib/ con la ruta que utilizaste en la instalacin de Twig. Si instalaste Twig va Composer puedes aprovechar el mecanismo de autocarga deComposer reemplazando el fragmento anterior por:
require_once '/ruta/a/vendor/autoload.php'

Nota
Twig sigue la convencin de nombres de PEAR para sus clases, lo cual significa que puedes integrar fcilmente las clases de Twig cargndolo en tu propio cargador automtico.
$loader = new Twig_Loader_String(); $twig = new Twig_Environment($loader);

echo $twig->render('Hello {{ name }}!', array('name' => 'Fabien'));

Twig utiliza un cargador (Twig_Loader_String) para buscar las plantillas, y un entorno (Twig_Environment) para almacenar la configuracin. El mtodo render() carga la plantilla pasada como primer argumento y la reproduce con las variables pasadas como segundo argumento.

Debido a que las plantillas generalmente se guardan en el sistema de archivos, Twigtambin viene con un cargador del sistema de archivos:
$loader = new Twig_Loader_Filesystem('/ruta/a/templates'); $twig = new Twig_Environment($loader, array( 'cache' => '/ruta/a/compilation_cache', ));

echo $twig->render('index.html', array('name' => 'Fabien'));

Twig para diseadores de plantillas

Este documento describe la sintaxis y semntica del motor de plantillas y ser muy til como referencia para quin est creando plantillas Twig.

Sinopsis
Una plantilla simplemente es un archivo de texto. Esta puede generar cualquier formato basado en texto (HTML, XML, CSV, LaTeX, etc.) No tiene una extensin especfica, .html o .xml estn muy bien. Una plantilla contiene variables o expresiones, las cuales se reemplazan por valores cuando se evala la plantilla, y las etiquetas, controlan la lgica de la plantilla. A continuacin mostramos una plantilla mnima que ilustra algunos conceptos bsicos. Veremos los detalles ms adelante en este documento:
<!DOCTYPE html> <html> <head> <title>My Webpage</title>

</head> <body> <ul id="navigation"> {% for item in navigation %} <li><a href="{{ item.href }}">{{ item.caption }}</a></li> {% endfor %} </ul>

<h1>My Webpage</h1> {{ a_variable }} </body> </html>

Hay dos tipos de delimitadores: {% ... %} y {{ ... }}. El primero se utiliza para ejecutar declaraciones como bucles for, el ltimo imprime en la plantilla el resultado de una expresin.

Integrando con IDEs

Los IDEs modernos son compatibles con el resaltado de sintaxis y autocompletado en una amplia gama de lenguajes.

Textmate va el paquete Twig Vim va el complemento de sintaxis Jinja Netbeans va el complemento de sintaxis Twig (hasta 7.1, nativo a partir de 7.2) PhpStorm (nativo desde la versin 2.1) Eclipse va el complemento Twig Sublime Text va el paquete Twig GtkSourceView va el Twig language definition (usado por gedit y otros proyectos)

Coda y SubEthaEdit va el modo de sintaxis Twig Coda 2 va el otro modo de sintaxis Twig Komodo y Komodo Edit va el modo resaltador/comprobador de sintaxis Twig Notepad++ va el Resaltador Notepad++ de Twig Emacs va web-mode.el

Variables
La aplicacin pasa variables a las plantillas para que puedas combinarlas en la plantilla. Las variables pueden tener atributos o elementos en ellas a los cuales puedes acceder tambin. Cmo se ve una variable, en gran medida, depende de la aplicacin que la proporcione. Puedes utilizar un punto (.) para acceder a los atributos de una variable (mtodos o propiedades de un objeto PHP, o elementos de un arreglo PHP), o la as llamada sintaxis de subndice ([]).
{{ foo.bar }} {{ foo['bar'] }}

Cuando el atributo contiene caracteres especiales (como el guin - se debe interpretar como el operador de sustraccin), en su lugar usa la funcin attribute()para acceder al valor de la variable attribute:
{# equivalente al no funcional foo.data-foo #} {{ attribute(foo, 'data-foo') }}

Nota
Es importante saber que las llaves no son parte de la variable, sino de la declaracin de impresin. Si accedes a variables dentro de las etiquetas no las envuelvas con llaves. Si no existe una variable o atributo, recibirs un valor nulo cuando la opcinstrict_variables est ajustada a false, de lo contrario Twig lanzar un error (consulta las opciones de entorno).

Implementacin Por razones de convenienciafoo.bar hace lo siguiente en la capa PHP:

Comprueba si foo es un arreglo y bar un elemento vlido; si no, y si foo es un objeto, comprueba que bar es una propiedad vlida; si no, y si foo es un objeto, comprueba que bar es un mtodo vlido (incluso si bares el constructor usa__construct() en su lugar);

si no, y si foo es un objeto, comprueba que getBar es un mtodo vlido; si no, y si foo es un objeto, comprueba que isBar es un mtodo vlido; si no, devuelve un valor null.

foo['bar']

por el contrario slo trabaja con arreglos PHP:

Comprueba si foo es un arreglo y bar un elemento vlido; si no, devuelve un valor null.

Nota
Si deseas obtener un atributo dinmico en una variable, utiliza la funcin attribute en su lugar.

Variables globales
Las siguientes variables siempre estn disponibles en las plantillas:
_self: hace referencia a la plantilla actual; _context: hace referencia al contexto actual; _charset: hace referencia al juego de caracteres actual.

Definiendo variables
Puedes asignar valores a las variables dentro de los bloques de cdigo. Las asignaciones usan la etiqueta set:
{% set foo = 'foo' %} {% set foo = [1, 2] %}

{% set foo = {'foo': 'bar'} %}

Filtros
Los filtros pueden modificar variables. Los filtros estn separados de la variable por un smbolo de tubo (|) y pueden tener argumentos opcionales entre parntesis. Puedes encadenar mltiples filtros. La salida de un filtro se aplica al siguiente. El siguiente ejemplo elimina todas las etiquetas HTML del name y lo formatea como nombre propio:
{{ name|striptags|title }}

Los filtros que aceptan argumentos llevan parntesis en torno a los argumentos. Este ejemplo unir una lista con comas:
{{ list|join(', ') }}

Para aplicar un filtro en una seccin de cdigo, envulvelo con la etiqueta filter:
{% filter upper %} Este texto cambia a maysculas {% endfilter %}

Ve a la pgina de filtros para aprender ms acerca de los filtros incorporados.

Funciones
Las funciones se pueden llamar para generar contenido. Las funciones son llamadas por su nombre seguido de parntesis (()) y pueden tener argumentos. Por ejemplo, la funcin range devuelve una lista que contiene una progresin aritmtica de nmeros enteros:
{% for i in range(0, 3) %}

{{ i }}, {% endfor %}

Ve a la pgina funciones para aprender ms acerca de las funciones incorporadas.

Argumentos nombrados
Nuevo en la versin 1.12: El soporte para los argumentos nombrados se aadi enTwig 1.12. Los argumentos para filtros y funciones tambin se pueden pasar como argumentos nombrados:
{% for i in range(low=1, high=10, step=2) %} {{ i }}, {% endfor %}

Utilizar argumentos nombrados hace tus plantillas ms explcitas sobre el significado de los valores que pasas como argumentos:
{{ data|convert_encoding('UTF-8', 'iso-2022-jp') }}

{# contra #}

{{ data|convert_encoding(from='iso-2022-jp', to='UTF-8') }}

Los argumentos nombrados tambin te permiten omitir algunos argumentos para los que no quieras cambiar el valor predefinido:
{# el primer argumento es el formato de fecha, el cual por omisin es el formato de fecha global si pasas null #} {{ "now"|date(null, "Europe/Paris") }}

{# u omites el valor de formato utilizando un argumento nombrado para timezone #} {{ "now"|date(timezone="Europe/Paris") }}

Tambin puedes utilizar ambos argumentos posicionales y nombrados en una llamada, lo cual no se recomienda cuando pueda provocar alguna confusin:
{# ambos trabajan #} {{ "now"|date('d/m/Y H:i', timezone="Europe/Paris") }} {{ "now"|date(timezone="Europe/Paris", 'd/m/Y H:i') }}

Truco
Cada funcin y pgina de documentacin del filtro tiene una seccin donde los nombres de todos los argumentos estn listados cundo cuentan con apoyo.

Estructuras de control
Una estructura de control se refiere a todas esas cosas que controlan el flujo de un programa condicionales (es decir, if/elseif/else), bucles for, as como cosas tales como bloques. Las estructuras de control aparecen dentro de bloques {% ... %}. Por ejemplo, para mostrar una lista de usuarios provista en una variable llamadausers, usa la etiqueta for:
<h1>Members</h1> <ul> {% for user in users %} <li>{{ user.username|e }}</li> {% endfor %} </ul>

Puedes utilizar la etiqueta if para probar una expresin:

{% if users|length > 0 %} <ul> {% for user in users %} <li>{{ user.username|e }}</li> {% endfor %} </ul> {% endif %}

Ve a la pgina etiquetas para aprender ms acerca de las etiquetas incorporadas.

Comentarios
Para comentar parte de una lnea en una plantilla, utiliza la sintaxis de comentario{# ... #}. Esta es til para depuracin o para agregar informacin para los diseadores de otra plantilla o para ti mismo:
{# nota: inhabilitado en la plantilla porque ya no se utiliza {% for user in users %} ... {% endfor %} #}

Incluyendo otras plantillas

La etiqueta include es til para incluir una plantilla y devolver el contenido producido de esa plantilla a la actual:
{% include 'sidebar.html' %}

De manera predeterminada se pasa el contexto actual a las plantillas incluidas. El contexto que se pasa a la plantilla incluida incorpora las variables definidas en la plantilla:

{% for box in boxes %} {% include "render_box.html" %} {% endfor %}

La plantilla incluida render_box.html es capaz de acceder a box. El nombre de archivo de la plantilla depende del gestor de plantillas. Por ejemplo, elTwig_Loader_Filesystem te permite acceder a otras plantillas, dando el nombre del archivo. Puedes acceder a plantillas en subdirectorios con una barra inclinada:
{% include "sections/articles/sidebar.html" %}

Este comportamiento depende de la aplicacin en que integres Twig.

Herencia en plantillas
La parte ms poderosa de Twig es la herencia entre plantillas. La herencia de plantillas te permite crear un esqueleto de plantilla base que contenga todos los elementos comunes de tu sitio y define los bloques que las plantillas descendientes pueden sustituir. Suena complicado pero es muy bsico. Es ms fcil entenderlo comenzando con un ejemplo. Vamos a definir una plantilla base, base.html, la cual define el esqueleto de un documento HTML simple que puedes usar para una sencilla pgina de dos columnas:
<!DOCTYPE html> <html> <head> {% block head %} <link rel="stylesheet" href="style.css" /> <title>{% block title %}{% endblock %} - My Webpage</title>

{% endblock %} </head> <body> <div id="content">{% block content %}{% endblock %}</div> <div id="footer"> {% block footer %} &copy; Copyright 2011 by <a href="http://dominio.invalido/"> t </a>. {% endblock %} </div> </body> </html>

En este ejemplo, las etiquetas block definen cuatro bloques que las plantillas herederas pueden rellenar. Todas las etiquetas block le dicen al motor de plantillas que una plantilla heredera puede sustituir esas porciones de la plantilla. Una plantilla hija podra tener este aspecto:
{% extends "base.html" %}

{% block title %}Index{% endblock %} {% block head %} {{ parent() }} <style type="text/css"> .important { color: #336699; } </style>

{% endblock %} {% block content %} <h1>Index</h1> <p class="important"> Bienvenido a mi impresionante pgina. </p> {% endblock %}

Aqu, la clave es la etiqueta extends. Esta le dice al motor de plantillas que esta plantilla extiende otra plantilla. Cuando el sistema de plantillas evala esta plantilla, en primer lugar busca la plantilla padre. La etiqueta extends debe ser la primera etiqueta en la plantilla. Ten en cuenta que debido a que la plantilla heredera no define el bloque footer, en su lugar se utiliza el valor de la plantilla padre. Es posible reproducir el contenido del bloque padre usando la funcin parent. Esta devuelve el resultado del bloque padre:
{% block sidebar %} <h3>Table Of Contents</h3> ... {{ parent() }} {% endblock %}

Truco
La pgina de documentacin para la etiqueta extends describe caractersticas ms avanzadas como el anidamiento de bloques, mbito, herencia dinmica, y herencia condicional.

Nota
Twig tambin es compatible con herencia mltiple por medio del as llamado reuso horizontal con la ayuda de la etiqueta use. Esta es una caracterstica que casi nunca se necesita en las plantillas normales.

Escapando HTML
Cuando generas HTML desde plantillas, siempre existe el riesgo de que una variable incluya caracteres que afecten el HTML resultante. Hay dos enfoques: escapar cada variable manualmente o de manera predeterminada escapar todo automticamente. Twig apoya ambos, el escape automtico est habilitado por omisin.

Nota
El escape automtico slo se admite si has habilitado la extensin escaper (el cual es el valor predeterminado).

Trabajando con el escape manual

Si el escape manual est habilitado, es tu responsabilidad escapar las variables si es necesario. Qu escapar? Cualquier variable en que no confes. El escape trabaja entubando la variable a travs del filtro escape o |e:
{{ user.username|e }}

De manera predeterminada, el filtro escape utiliza la estrategia html, pero dependiendo del contexto a escapar, posiblemente desees usar otras estrategias disponibles explcitamente:
{{ user.username|e(js) }} {{ user.username|e(css) }} {{ user.username|e(url) }} {{ user.username|e(html_attr) }}

Trabajando con escape automtico

Ya sea que el escape automtico est habilitado o no, puedes marcar una seccin de una plantilla para que sea escapada o no utilizando la etiqueta autoescape:
{% autoescape %} En este bloque, todo se escapar automticamente (usando la estrategia HTML)

{% endautoescape %}

De manera predeterminada, el autoescape utiliza la estrategia de escape HTML. Si sacas variables en otros contextos, es necesario escaparlas explcitamente con la estrategia de escape adecuada:
{% autoescape 'js' %} En este bloque, todo se escapar automticamente (usando la estrategia JS) {% endautoescape %}

Escapando
A veces es deseable e incluso necesario contar con que Twig omita partes que de lo contrario manejara como variables o bloques. Por ejemplo, si utilizas la sintaxis predeterminada y deseas utilizar {{ como cadena sin procesar en la plantilla y no iniciar una variable, tienes que usar un truco. La forma ms sencilla es extraer la variable del delimitador ( {{) usando una expresin variable:
{{ '{{' }}

Para grandes secciones tiene sentido marcar un bloque como verbatim.

Macros
Nuevo en la versin 1.12: El soporte para valores predefinidos de argumentos se aadi en Twig 1.12. Las macros son comparables con funciones en lenguajes de programacin regulares. Son tiles para reutilizar HTML usado frecuentemente para no repetirlos t mismo. Una macro se define a travs de la etiqueta macro. Aqu est un pequeo ejemplo (ms tarde llamada forms.html) de una macro que pinta un elemento de formulario:

{% macro input(name, value, type, size) %} <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" /> {% endmacro %}

Puedes definir macros en cualquier plantilla, y necesitas importarlas con la etiqueta import antes de poder usarlas:
{% import "formularios.html" as forms %}

<p>{{ forms.input('username') }}</p>

Alternativamente, puedes importar nombres de macros individuales desde una plantilla al espacio de nombres actual va la etiqueta from:
{% importa el input de 'forms.html' como input_field %}

<dl> <dt>Username</dt> <dd>{{ input_field('username') }}</dd> <dt>Password</dt> <dd>{{ input_field('password', '', 'password') }}</dd> </dl>

Tambin puedes definir valores predefinidos para argumentos de macros cuando no se proporcionen en una llamada a la macro:
{% macro input(name, value = "", type = "text", size = 20) %}

<input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}" /> {% endmacro %}

Expresiones
Twig acepta expresiones en cualquier parte. Estas funcionan de manera muy similar a PHP regular e incluso si no ests trabajando con PHP te debes sentir cmodo con estas.

Nota
La precedencia de los operadores es la siguiente, mostrando los operadores de menor precedencia en primer lugar: b-and, b-xor, b-or, or, and, ==, ! =, <, >, >=, <=, in, .., +, -,~, *, /, //, %, is, and **.

Literales
Nuevo en la versin 1.5: El soporte para codificar claves como nombres y expresiones se aadi en Twig 1.5. La forma ms simple de las expresiones son literales. Los literales son representaciones para tipos PHP, tal como cadenas, nmeros y arreglos. Existen los siguientes literales:
"Hello World": Todo lo que est entre comillas

simples o dobles es una cadena. Son tiles cuando necesitas una cadena en la plantilla (por ejemplo, como argumentos para llamadas a funcin, filtros o simplemente para extender o incluir una plantilla). 42 / 42.23: Nmeros enteros y nmeros en coma flotante se crean tan slo escribiendo el nmero. Si est presente un punto es un nmero en coma flotante, de lo contrario es un nmero entero.
["foo", "bar"]: Los arreglos se definen por medio de una secuencia de

expresiones separadas por una coma (,) y envueltas entre corchetes ([]).
{"foo": "bar"}: Los valores hash se definen con una lista de claves y

valores separados por una coma (,) y envueltos entre llaves ({}).

{# claves como cadena #} { 'foo': 'foo', 'bar': 'bar' }

{# claves como nombres (equivalente al hash anterior) -- a partir de Twig 1.5 #} { foo: 'foo', bar: 'bar' }

{# claves como entero #} { 2: 'foo', 4: 'bar' }

{# claves como expresiones (la expresin se debe encerrar entre parntesis) -- a partir de Twig 1.5 #} { (1 + 1): 'foo', (a ~ 'b'): 'bar' } true / false: true

representa el valor verdadero, false representa el valor

falso.
null: null no representa un valor especfico. Este es el valor devuelto

cuando una variable no existe. none es un alias para null. Los arreglos y hashes se pueden anidar:
{% set foo = [1, {"foo": "bar"}] %}

Truco
Utilizar comillas dobles o sencillas en cadenas no tiene ningn impacto en el rendimiento pero la interpolacin de cadenas slo cuenta con apoyo en cadenas entre comillas dobles.

Matemticas
Twig te permite calcular valores. Esto no suele ser til en las plantillas, pero existe por el bien de la integridad. Admite los siguientes operadores:

+: Suma dos objetos (los operandos se convierten a nmeros). {{ 1 + 1 }} is 2. -: Resta el segundo nmero del primero. {{ 3 - 2 }} es 1. /: Divide dos nmeros. El valor devuelto ser un nmero en punto

flotante. {{ 1/ 2 }} es {{ 0.5 }}.

%: Calcula el residuo de una divisin entera. {{ 11 % 7 }} es 4. //: Divide dos nmeros y devuelve el resultado entero

truncado. {{ 20 // 7 }}es 2.
*: Multiplica el operando de la izquierda con el de la

derecha. {{ 2 * 2 }}devolver 4.
**: Eleva el operando izquierdo a la potencia del operando

derecho. {{ 2 ** 3}} devolver 8.

Lgica
Puedes combinar varias expresiones con los siguientes operadores:
and: Devuelve true si ambos operandos izquierdo y derecho son true. or: Devuelve true si el operando izquierdo o derecho es true. not: Niega una declaracin. (expr): Agrupa una expresin.

Nota
Twig adems es compatible con operadores a nivel de bits (b-and, b-xor, and bor).

Comparaciones
Los siguientes operadores de comparacin son compatibles con cualquier expresin:==, !=, <, >, >=, y <=.

Operador de contencin
El operador in realiza la prueba de contencin. Esta devuelve true si el operando de la izquierda figura entre los de la derecha:

{# devuelve true #}

{{ 1 in [1, 2, 3] }}

{{ 'cd' in 'abcde' }}

Truco
Puedes utilizar este filtro para realizar una prueba de contencin en cadenas, arreglos u objetos que implementan la interfaz Traversable. Para llevar a cabo una prueba negativa, utiliza el operador not in:
{% if 1 not in [1, 2, 3] %}

{# es equivalente a #} {% if not (1 in [1, 2, 3]) %}

Operador de prueba
El operador is realiza pruebas. Puedes utilizar las pruebas para comprobar una variable con una expresin comn. El operando de la derecha es el nombre de la prueba:
{# averigua si una variable es impar #}

{{ nombre is odd }}

Las pruebas tambin pueden aceptar argumentos:

{% if loop.index is divisibleby(3) %}

Puedes negar las pruebas usando el operador is not:

{% if loop.index is not divisibleby(3) %}

{# es equivalente a #} {% if not (loop.index is divisibleby(3)) %}

Ve a la pgina Probando para aprender ms sobre las pruebas integradas.

Otros operadores
Nuevo en la versin 1.12.0: El soporte para el operador ternario extendido se aadi en Twig 1.12.0. Los siguientes operadores son muy tiles pero no encajan en ninguna de las otras dos categoras:
..: Crea una secuencia basada en el operando antes y despus del

operador (esta slo es pura azcar sintctica para la funcin range). |: Aplica un filtro.
~: Convierte todos los operandos en cadenas y los

concatena. {{ "Hello " ~ name~ "!" }} debera devolver (suponiendo que name es 'John') Hello John!.
{# a partir de Twig 1.12.0 #} {{ foo ?: 'no' }} == {{ foo ? foo : 'no' }} ., []: Obtiene un atributo ?:: El operador ternario: {{ foo ? 'yes' : 'no' }}

de un objeto.

{{ foo ? 'yes' }} == {{ foo ? 'yes' : '' }}

Interpolando cadenas
Nuevo en la versin 1.5: La interpolacin de cadenas se aadi en Twig 1.5. La interpolacin de cadenas (#{expresin}) permite que cualquier expresin vlida aparezca dentro de una cadena entre comillas dobles. El resultado de la evaluacin esa expresin se inserta en la cadena:
{{ "foo #{bar} baz" }} {{ "foo #{1 + 2} baz" }}

Controlando el espacio en blanco

Nuevo en la versin 1.1: La etiqueta para controlar el nivel de los espacios en blanco se aadi en Twig 1.1. La primer nueva lnea despus de una etiqueta de plantilla se elimina automticamente (como en PHP). El motor de plantillas no modifica el espacio en blanco, por lo tanto cada espacio en blanco (espacios, tabuladores, nuevas lneas, etc.) se devuelve sin cambios. Utiliza la etiqueta spaceless para quitar los espacios en blanco entre las etiquetasHTML:
{% spaceless %} <div> <strong>foo</strong> </div> {% endspaceless %}

{# Producir <div><strong>foo</strong></div> #}

Adems de la etiqueta spaceless tambin puedes controlar los espacios en blanco a nivel de etiquetas. Utilizando el modificador de control de los espacios en blanco en tus etiquetas, puedes recortar los espacios en blanco en ambos extremos:

{% set value = 'no spaces' %} {#- No deja espacios en blanco en ambos extremos -#} {%- if true -%} {{- value -}} {%- endif -%}

{# produce 'sin espacios' #}

El ejemplo anterior muestra el modificador de control de espacios en blanco predeterminado, y cmo lo puedes utilizar para quitar los espacios en blanco alrededor de las etiquetas. Recortar el espacio debe consumir todos los espacios en blanco a ese lado de la etiqueta. Es posible utilizar el recorte de espacios en blanco en un lado de una etiqueta:
{% set value = 'no spaces' %} <li> {{- value }} </li>

{# produce '<li>no spaces

</li>' #}

Extendiendo
Puedes extender Twig fcilmente. Si ests buscando nuevas etiquetas, filtros, o funciones, chale un vistazo alrepositorio de extensiones oficial de Twig. Si deseas crear una propia, lee el captulo Creando una extensin.

Twig para desarrolladores

Este captulo describe la API para Twig y no el lenguaje de plantillas. Ser muy til como referencia para aquellos que implementan la interfaz de plantillas para la aplicacin y no para los que estn creando plantillas Twig.

Fundamentos
Twig utiliza un objeto central llamado entorno (de la clase Twig_Environment). Las instancias de esta clase se utilizan para almacenar la configuracin y extensiones, y se utilizan para cargar plantillas dede el sistema de archivos o en otros lugares. La mayora de las aplicaciones debe crear un objeto Twig_Environment al iniciar la aplicacin y usarlo para cargar plantillas. En algunos casos, sin embargo, es til disponer de mltiples entornos lado a lado, si ests usando distintas configuraciones. La forma ms sencilla de configurar Twig para cargar plantillas para tu aplicacin se ve ms o menos as:
require_once '/ruta/a/lib/Twig/Autoloader.php'; Twig_Autoloader::register();

$loader = new Twig_Loader_Filesystem('/ruta/a/templates'); $twig = new Twig_Environment($loader, array( 'cache' => '/ruta/a/compilation_cache', ));

Esto crear un entorno de plantillas con la configuracin predeterminada y un cargador que busca las plantillas en el directorio /ruta/a/templates/. Hay diferentes cargadores disponibles y tambin puedes escribir el tuyo si deseas cargar plantillas de una base de datos u otros recursos.

Nota
Ten en cuenta que el segundo argumento del entorno es un arreglo de opciones. La opcin cache es un directorio de cach de compilacin, donde Twig memoriza las plantillas compiladas para evitar la fase de anlisis de las subsiguientes peticiones. Esta es muy diferente de la cach que posiblemente desees agregar para evaluar plantillas. Para tal necesidad, puedes utilizar cualquier biblioteca de cach PHPdisponible.

Para cargar una plantilla desde este entorno slo tienes que llamar al mtodoLoadTemplate() el cual devuelve una instancia de Twig_Template:
$template = $twig->loadTemplate('index.html');

Para reproducir la plantilla con algunas variables, llama al mtodo render():

echo $template->render(array('the' => 'variables', 'go' => 'here'));

Nota
El mtodo display() es un atajo para reproducir la plantilla directamente. Tambin puedes exponer los mtodos de extensin como funciones en tus plantillas:
echo $twig->render( 'index.html', array( 'the' => 'variables', 'go' => 'here' ));

Opciones del entorno

Al crear una nueva instancia de Twig_Environment, puedes pasar un arreglo de opciones como segundo argumento del constructor:
$twig = new Twig_Environment($loader, array('debug' => true));

Las siguientes opciones estn disponibles:

debug: Cuando se establece en true, las plantillas generadas tienen un

mtodo__toString() que puedes utilizar para mostrar los nodos generados (el

predeterminado es false). charset: El juego de caracteres usado por las plantillas (por omisin es utf-8).
base_template_class: La clase de la plantilla base utilizada para generar

plantillas (por omisin Twig_Template).

cache: Una ruta absoluta donde almacenar las plantillas compiladas,

o falsepara desactivar el almacenamiento en cach (el cual es el valor predeterminado).

auto_reload: Cuando desarrollas con Twig, es til volver a compilar la plantilla

cada vez que el cdigo fuente cambia. Si no proporcionas un valor para la opcin auto_reload, se determinar automticamente en funcin del valordebug.
strict_variables: Si se establece en false, Twig ignorar silenciosamente las

variables no vlidas (variables y/o atributos/mtodos que no existen) y los reemplazar con un valor null. Cuando se establece en true, Twig produce una excepcin en su lugar (el predeterminado es false).
autoescape: Si se establece en true, el escape automtico ser habilitado de

manera predeterminada para todas las plantillas (por omisin es true). A partir de Twig 1.8, puedes configurar la estrategia de escape a utilizar (html, js, falsepara desactivarla). A partir de Twig 1.9, puedes configurar la estrategia de escape a utilizar (css, url, html_attr, o una retrollamada PHP que toma la plantilla nombrearchivo y tiene que regresar la estrategia de escape a utilizar la retrollamada no puede ser un nombre de funcin para evitar colisiones con las estrategias de escape incorporadas).
optimizations: Una marca que indica cuales optimizaciones aplicar (por

omisin a -1 todas las optimizaciones estn habilitadas; para desactivarla ponla a 0).

Cargadores
Los cargadores son responsables de cargar las plantillas desde un recurso como el sistema de archivos.

Cach de compilacin
Todos los cargadores de plantillas en cach pueden compilar plantillas en el sistema de archivos para su futura reutilizacin. Esto acelera mucho cmo se compilan las plantillas Twig una sola vez; y el aumento del rendimiento es an mayor si utilizas un acelerador PHP como APC. Consulta las opciones anteriores cache y auto_reloadde Twig_Environment para ms informacin.

Cargadores integrados
Aqu est una lista de los cargadores incorporados de que dispone Twig:

Twig_Loader_Filesystem
Nuevo en la versin 1.10: El soporte para prependPath() y para los espacios de nombres se aadi en Twuig 1.10.
Twig_Loader_Filesystem: Carga plantillas

desde el sistema de archivos. Este cargador puede encontrar plantillas en los directorios del sistema de archivos y es la manera preferida de cargarlas:
$loader = new Twig_Loader_Filesystem($templateDir);

Tambin puedes buscar plantillas en un arreglo de directorios:

$loader = new Twig_Loader_Filesystem( array( $templateDir1, $templateDir2 ));

Con esta configuracin, Twig primero buscar las plantillas en $templateDir1 y si no existen, regresar a buscar en $templateDir2. Puedes aadir o prefijar rutas a travs de los mtodos addPath() y prependPath():
$loader->addPath($templateDir3); $loader->prependPath($templateDir4);

El cargador del sistema de archivos tambin apoya los espacios de nombres en plantillas. Esto te permite agrupar tus plantillas bajo diferentes espacios de nombres, los cules tienen sus propias rutas de plantilla. Cundo utilices los mtodos setPaths(), addPath() y prependPath(), especifica el espacio de nombres como el segundo argumento (cuando no lo especificas, estos mtodos actan en el espacio de nombres main):

$loader->addPath($templateDir, 'admin');

Las plantillas en los espacios de nombres se pueden acceder a travs de la notacin especial @nombre_del_espacio_de_nombres/ruta_a_plantilla:
$twig->render('@admin/index.html', array());

Twig_Loader_String
carga plantillas desde cadenas. Es un cargador simulado como referencia a la plantilla es el cdigo fuente de la plantilla:
Twig_Loader_String $loader = new Twig_Loader_String(); $twig = new Twig_Environment($loader);

echo $twig->render('Hello {{ name }}!', array('name' => 'Fabien'));

Este cargador slo se debe utilizar en las pruebas unitarias, ya que tiene serias limitaciones: varias etiquetas, tal como extends o include no tiene sentido que se utilicen como referencia a la plantilla puesto que es el cdigo fuente de la plantilla en s.

Twig_Loader_Array
carga una plantilla a partir de un arreglo PHP. Se le pasa un arreglo de cadenas vinculadas a los nombres de plantilla:
Twig_Loader_Array $loader = new Twig_Loader_Array(array( 'index.html' => 'Hello {{ name }}!', )); $twig = new Twig_Environment($loader);

echo $twig->render('index.html', array('name' => 'Fabien'));

Este cargador es muy til en las pruebas unitarias. Tambin puede ser til en proyectos pequeos donde tiene sentido almacenar todas las plantillas en un nico archivo PHP.

Truco
Cuando utilices los cargadores de Array o String con un mecanismo de cach, debes saber que se genera una nueva clave de cach cada vez que cambia el contenido de una plantilla (la clave de cach es el cdigo fuente de la plantilla). Si no deseas ver que tu cach crezca fuera de control, es necesario tener cuidado de limpiar el archivo de cach antiguo en s mismo.

Twig_Loader_Chain
Twig_Loader_Chain

delega la carga de plantillas a otros cargadores:

$loader1 = new Twig_Loader_Array(array( 'base.html' => '{% block content %}{% endblock %}', )); $loader2 = new Twig_Loader_Array(array( 'index.html' => '{% extends "base.twig" %}{% block content %}Hello {{ name }} {% endblock %}', 'base.html' => 'Will never be loaded', ));

$loader = new Twig_Loader_Chain(array($loader1, $loader2));

$twig = new Twig_Environment($loader);

Al buscar una plantilla, Twig probar cada cargador en turno y regresar tan pronto como encuentre la plantilla. Al reproducir la plantilla index.html del ejemplo anterior, Twig la cargar con $loader2 pero la plantilla base.html ser cargada desde$loader1. acepta cualquier cargador que implemente Twig_LoaderInterface.
Twig_Loader_Chain

Nota
Tambin puedes aadir cargadores a travs del mtodo addLoader().

Creando tu propio cargador

Todos los cargadores implementan la interfaz Twig_LoaderInterface:
interface Twig_LoaderInterface { /** * Obtiene el cdigo fuente de la plantilla del nombre dado. * * @param string $name cadena del nombre de la plantilla a cargar * * @return string El cdigo fuente de la plantilla */ function getSource($name);

/** * Obtiene la clave de la cach para usarla en un nombre de plantilla dado. * * @param string $name cadena del nombre de la plantilla a cargar * * @return string La clave de cach */ function getCacheKey($name);

/**

* Devuelve true si la plantilla an est fresca. * * @param string $name El nombre de la plantilla

* @param timestamp $time Hora de la ltima modificacin de la plantilla * */ function isFresh($name, $time); } en cach

A modo de ejemplo, esto es lo que dice el Twig_Loader_String incorporado:

class Twig_Loader_String implements Twig_LoaderInterface { public function getSource($name) { return $name; }

public function getCacheKey($name) { return $name; }

public function isFresh($name, $time) { return false; }

El mtodo isFresh() debe devolver true si la plantilla actual en cach an es fresca, dado el tiempo de la ltima modificacin, o false de lo contrario.

Truco
A partir de Twig 1.11.0, tambin puedes implementar la Twig_ExistsLoaderInterfacepara hacer tus cargadores ms rpidos al utilizarlos con el cargador de cadena.

Usando extensiones
Las extensiones Twig son paquetes que aaden nuevas caractersticas a Twig. Usar una extensin es tan simple como usar el mtodo addExtension():
$twig->addExtension(new Twig_Extension_Sandbox());

Twig viene con las siguientes extensiones:

Twig_Extension_Core: Define todas las caractersticas bsicas de Twig. Twig_Extension_Escaper: Agrega escape automtico y la posibilidad de escapar/no escapar bloques de cdigo.

Twig_Extension_Sandbox: Agrega un modo de recinto de seguridad para el entorno predeterminado de Twig, en el cual es seguro evaluar cdigo que no es de confianza.

Twig_Extension_Optimizer: Optimiza el nodo del rbol antes de la compilacin.

El ncleo, las extensiones del mecanismo de escape y optimizacin no es necesario aadirlas al entorno Twig, debido a que se registran de forma predeterminada.

Extensiones incorporadas
Esta seccin describe las caractersticas agregadas por las extensiones incorporadas.

Truco
Lee el captulo sobre la ampliacin de Twig para que veas cmo crear tus propias extensiones.

Extensin core
La extensin core define todas las caractersticas principales de Twig:

Etiquetas;
o o o o o o o o o o o o o o o o o o for if extends include block filter macro import from set spaceless autoescape do embed flush verbatim sandbox use

Filtros:
o date

o o o o o o o o o o o o o o o o o o o o o o o o o o

format replace url_encode json_encode title capitalize upper lower striptags join reverse length sort merge default keys escape e abs convert_encoding date_modify nl2br number_format raw slice trim

Funciones:
o o o o o o o o o range constant cycle parent block attribute date dump random

Pruebas:
o o o o o o o o o even odd defined sameas null divisibleby constant empty iterable

Extensin escaper
La extensin escaper aade a Twig el escape automtico de la salida. Esta define una nueva etiqueta, autoescape, y un filtro raw. Al crear la extensin escaper, puedes activar o desactivar la estrategia de escape global de la salida:

$escaper = new Twig_Extension_Escaper(true); $twig->addExtension($escaper);

Si la estableces a true, se escapan todas las variables en las plantillas, excepto las que utilizan el filtro raw:
{{ article.to_html|raw }}

Tambin puedes cambiar el modo de escape a nivel local usando la etiquetaautoescape (consulta la documentacin para la sintaxis usada por el autoescapeantes de la versin 1.8 de Twig):
{% autoescape 'html' %} {{ var }} {{ var|raw }} {# var no se escapa #}

{{ var|escape }} {# var no se escapa doblemente #} {% endautoescape %}

Advertencia
La etiqueta autoescape no tiene ningn efecto sobre los archivos incluidos. Las reglas de escape se implementan de la siguiente manera:

Literales (enteros, booleanos, arreglos, ...) utilizados en la plantilla directamente como variables o argumentos de filtros no son escapados automticamente:
{{ "Twig<br />" }} {# no se escapa #}

{% set text = "Twig<br />" %} {{ text }} {# ser escapado #}

Expresiones cuyo resultado siempre es un literal o una variable marcada como segura nunca sern escapadas automticamente:

{{ foo ? "Twig<br />" : "<br />Twig" }} {# no ser escapado #}

{% set text = "Twig<br />" %} {{ foo ? text : "<br />Twig" }} {# ser escapado #}

{% set text = "Twig<br />" %} {{ foo ? text|raw : "<br />Twig" }} {# no ser escapado #}

{% set text = "Twig<br />" %} {{ foo ? text|escape : "<br />Twig" }} {# el resultado de la expresin

no ser escapado #}

El escape se aplica antes de la impresin, despus de haber aplicado cualquier otro filtro:
{{ var|upper }} {# es equivalente a {{ var|upper|escape }} #}

El filtro raw slo se debe utilizar al final de la cadena de filtros:

{{ var|raw|upper }} {# se deber escapar #}

{{ var|upper|raw }} {# no ser escapado #}

No se aplica el escape automtico si el ltimo filtro de la cadena est marcado como seguro para el contexto actual (por ejemplo, html o js). escaper yescaper('html') estn marcados como seguros para html, escaper('js') est marcado como seguro para javascript, raw est marcado como seguro para todo.
{% autoescape 'js' %} {{ var|escape('html') }} {# ser escapado para html y javascript #}

{{ var }} {# ser escapado para javascript #} {{ var|escape('js') }} {# no se escapar doblemente #} {% endautoescape %}

Nota
Ten en cuenta que el escape automtico tiene algunas limitaciones puesto que el escapado se aplica en las expresiones despus de su evaluacin. Por ejemplo, cuando trabajas en concatenacin, {{foo|raw ~ bar }} no dar el resultado esperado ya que el escape se aplica sobre el resultado de la concatenacin y no en las variables individuales (por lo tanto aqu, el filtro raw no tendr ningn efecto).

Extensin sandbox
La extensin sandbox se puede utilizar para evaluar cdigo no confiable. El acceso a los atributos y los mtodos inseguros est prohibido. El entorno recinto de seguridad es manejado por una poltica de la instancia. Por omisin, Twig viene con una poltica de clase: Twig_Sandbox_SecurityPolicy. Esta clase te permite agregar a la lista blanca algunas etiquetas, filtros, propiedades y mtodos:
$tags = array('if'); $filters = array('upper'); $methods = array( 'Article' => array( 'getTitle', 'getBody' ), ); $properties = array( 'Article' => array( 'title', 'body' ), ); $functions = array('range');

$policy = new Twig_Sandbox_SecurityPolicy( $tags, $filters, $methods, $properties, $functions );

Con la configuracin anterior, la poltica de seguridad slo te permitir usar los filtros if, tag y upper. Por otra parte, las plantillas slo podrn llamar a los mtodosgetTitle() y getBody() en objetos Article, y a las propiedades pblicas title y body. Todo lo dems no est permitido y se generar una excepcinTwig_Sandbox_SecurityError. El objeto poltica es el primer argumento del constructor del recinto de seguridad:
$sandbox = new Twig_Extension_Sandbox($policy); $twig->addExtension($sandbox);

De forma predeterminada, el modo de recinto de seguridad est desactivado y se activa cuando se incluye cdigo de plantilla que no es de confianza usando la etiqueta sandbox:
{% sandbox %} {% include 'user.html' %} {% endsandbox %}

Puedes poner todas las plantillas en el recinto de seguridad pasando true como segundo argumento al constructor de la extensin:
$sandbox = new Twig_Extension_Sandbox($policy, true);

Extensin optimizer
La extensin optimizer optimiza el nodo del rbol antes de compilarlo:

$twig->addExtension(new Twig_Extension_Optimizer());

Por omisin, todas las optimizaciones estn activadas. Puedes seleccionar las que desees habilitar pasndolas al constructor:
$optimizer = new Twig_Extension_Optimizer( Twig_NodeVisitor_Optimizer::OPTIMIZE_FOR);

$twig->addExtension($optimizer);

Excepciones
Twig puede lanzar excepciones:
Twig_Error: La excepcin base para todos los errores. Twig_Error_Syntax: Lanzada para indicar al usuario que hay un problema con la

sintaxis de la plantilla.
Twig_Error_Runtime: Lanzada cuando se produce un error en tiempo de

ejecucin (cuando un filtro no existe, por ejemplo).

Twig_Error_Loader: Se lanza al producirse un error durante la carga de la

plantilla.
Twig_Sandbox_SecurityError: Lanzada cuando aparece una etiqueta, filtro, o se

llama a un mtodo no permitido en una plantilla de un recinto de seguridad.

Extendiendo Twig
Prudencia
Esta seccin describe cmo extender Twig a partir de Twig 1.12. Si ests usando una versin anterior, en vez de esta lee el captulo del legado. Twig se puede extender en muchos aspectos; puedes aadir etiquetas adicionales, filtros, pruebas, operadores, variables globales y funciones. Incluso puedes extender el propio analizador con visitantes de nodo.

Nota

La primer seccin de este captulo describe la forma de extender Twig fcilmente. Si deseas volver a utilizar tus cambios en diferentes proyectos o si deseas compartirlos con los dems, entonces, debes crear una extensin tal como se describe en la siguiente seccin.

Prudencia
Al extender Twig sin crear una extensin, Twig no ser capaz de volver a compilar tus plantillas al actualizar el cdigo de PHP. Para ver tus cambios en tiempo real, o bien desactiva la memorizacin de plantillas o empaca tu cdigo en una extensin (ve la siguiente seccin de este captulo). Antes de extender Twig, debes entender las diferencias entre todos los diferentes puntos de extensin posibles y cundo utilizarlos. En primer lugar, recuerda que el lenguaje de Twig tiene dos construcciones principales:
{{ }}: Utilizada para imprimir el resultado de la evaluacin de la expresin; {% %}: Utilizada para ejecutar instrucciones.

Para entender por qu Twig expone tantos puntos de extensin, vamos a ver cmo implementar un generador Lorem ipsum (este necesita saber el nmero de palabras a generar). Puedes utilizar una etiqueta Lipsum:
{% lipsum 40 %}

Eso funciona, pero usar una etiqueta para lipsum no es una buena idea por al menos tres razones principales:

no es una construccin del lenguaje; La etiqueta produce algo;

lipsum

La etiqueta no es flexible ya que no la puedes utilizar en una expresin:

{{ 'algn texto' ~ {% lipsum 40 %} ~ 'algo ms de texto' }}

De hecho, rara vez es necesario crear etiquetas; y es una muy buena noticia porque las etiquetas son el punto de extensin ms complejo de Twig. Ahora, vamos a utilizar un filtro lipsum:

{{ 40|lipsum }}

Una vez ms, funciona, pero se ve raro. Un filtro transforma el valor pasado a algo ms pero aqu utilizamos el valor para indicar el nmero de palabras a generar (as que, 40 es un argumento del filtro, no el valor que se va a transformar). En seguida, vamos a utilizar una funcin lipsum:
{{ lipsum(40) }}

Aqu vamos. Para este ejemplo concreto, la creacin de una funcin es el punto de extensin a usar. Y la puedes usar en cualquier lugar en que se acepte una expresin:
{{ 'some text' ~ lipsum(40) ~ 'some more text' }}

{% set lipsum = lipsum(40) %}

Por ltimo pero no menos importante, tambin puedes utilizar un objeto global con un mtodo capaz de generar texto Lorem Ipsum:
{{ text.lipsum(40) }}

Como regla general, utiliza funciones para las caractersticas ms utilizadas y objetos globales para todo lo dems. Ten en cuenta lo siguiente cuando quieras extender Twig:
Qu? macro global function filter dificultad para implementarlo? trivial trivial trivial trivial Con qu frecuencia? frecuente frecuente frecuente frecuente Cundo? Generacin de contenido Objeto ayudante Generacin de contenido Transformacin de valor

Qu?

dificultad para implementarlo? complejo trivial trivial

Con qu frecuencia? raro raro raro

Cundo? Constructor del lenguaje DSL Decisin booleana Transformacin de valores

tag test operato r

Globales
Una variable global es como cualquier otra variable de plantilla, excepto que est disponible en todas las plantillas y macros:
$twig = new Twig_Environment($loader); $twig->addGlobal('text', new Text());

Entonces puedes utilizar la variable text en cualquier parte de una plantilla:

{{ text.lipsum(40) }}

Filtros
Crear un filtro es tan sencillo como asociar un nombre con un ejecutable PHP:
// una funcin annima $filter = new Twig_SimpleFilter('rot13', function ($string) { return str_rot13($string); });

// o una simple funcin PHP $filter = new Twig_SimpleFilter('rot13', 'str_rot13');

// o un mtodo de clase $filter = new Twig_SimpleFilter('rot13', array('SomeClass', 'rot13Filter'));

El primer argumento pasado al constructor de Twig_Filter_Function es el nombre del filtro que usars en las plantillas y el segundo es el ejecutable PHP asociado. Luego, aade el filtro a tu entorno Twig:
$twig = new Twig_Environment($loader); $twig->addFilter($filter);

Y aqu tienes cmo utilizarlo en una plantilla:

{{ 'Twig'|rot13 }}

{# producir Gjvt #}

Cuando es llamado por Twig, el ejecutable PHP en el lado izquierdo recibe el filtro (antes de la barra vertical |) como primer argumento y los argumentos extras pasados al filtro (dentro de parntesis ()) como argumentos extra. Por ejemplo, el siguiente cdigo:
{{ 'TWIG'|lower }} {{ now|date('d/m/Y') }}

se compila a algo como lo siguiente:

<?php echo strtolower('TWIG') ?> <?php echo twig_date_format_filter($now, 'd/m/Y') ?>

La clase Twig_SimpleFilter toma un arreglo de opciones como ltimo argumento:

$filter = new Twig_SimpleFilter('rot13', 'str_rot13', $options);

Entorno consciente de filtros

Si en tu filtro quieres acceder a la instancia del entorno actual, pon a true la opcinneeds_environment; Twig pasar el entorno actual como primer argumento al llamar al filtro:
$filter = new Twig_SimpleFilter('rot13', function (Twig_Environment $env, $string) { // obtiene el juego de caracteres actual, por ejemplo $charset = $env->getCharset();

return str_rot13($string); }, array('needs_environment' => true));

Filtros conscientes del contexto

Si quieres acceder al contexto actual en tu filtro, pon a true la opcin needs_context;Twig pasar el contexto actual como primer argumento al llamar al filtro (o el segundo si needs_environment tambin es true):
$filter = new Twig_SimpleFilter('rot13', function ($context, $string) { // ... }, array('needs_context' => true));

$filter = new Twig_SimpleFilter('rot13', function (Twig_Environment $env, $context, $string) { // ... }, array('needs_context' => true, 'needs_environment' => true));

Escapando automticamente
Si est habilitado el escape automtico, puedes escapar la salida del filtro antes de imprimir. Si tu filtro acta como un escapista (o explcitamente produce

cdigo htmlo javascript), desears que se imprima la salida sin procesar. En tal caso, establece la opcin is_safe:
$filter = new Twig_SimpleFilter('nl2br', 'nl2br', array('is_safe' => array('html')));

Algunos filtros posiblemente tengan que trabajar en entradas que ya se escaparon o son seguras, por ejemplo, al agregar etiquetas HTML (seguras) inicialmente inseguras para salida. En tal caso, establece la opcin pre_escape para escapar los datos entrantes antes de pasarlos por tu filtro:
$filter = new Twig_SimpleFilter('somefilter', 'somefilter', array('pre_escape' => 'html', 'is_safe' => array('html')));

Filtros dinmicos
Un nombre de filtro que contiene el carcter especial * es un filtro dinmico debido a que el * puede ser cualquier cadena:
$filter = new Twig_SimpleFilter('*_path', function ($name, $arguments) { // ... });

Los siguientes filtros deben corresponder con el filtro dinmico definido anteriormente:
product_path category_path

Un filtro dinmico puede definir ms de una parte dinmica:

$filter = new Twig_SimpleFilter('*_path', function ($name, $suffix, $arguments) { // ... });

El filtro recibir todas las partes dinmicas de los valores antes de los argumentos de los filtros normales, pero despus del entorno y el contexto. Por

ejemplo, una llamada a 'foo'|a_path_b() resultar en que se pasarn los siguientes argumentos al filtro: ('a', 'b', 'foo').

Funciones
Las funciones estn definidas exactamente de la misma manera que los filtros, pero necesitas crear una instancia de Twig_SimpleFunction:
$twig = new Twig_Environment($loader); $function = new Twig_SimpleFunction('function_name', function () { // ... }); $twig->addFunction($function);

Las funciones apoyan las mismas caractersticas que los filtros, excepto por las opciones pre_escapr y preserves_safety.

Pruebas
Las pruebas se definen exactamente de la misma manera que los filtros y funciones, pero necesitas crear una instancia de Twig_SimpleTest:
$twig = new Twig_Environment($loader); $test = new Twig_SimpleTest('test_name', function () { // ... }); $twig->addTest($test);

Las pruebas no apoyan algunas opciones.

Etiquetas
Una de las caractersticas ms interesantes de un motor de plantillas como Twig es la posibilidad de definir nuevas construcciones del lenguaje. Esta

tambin es la caracterstica ms compleja que necesitas comprender de cmo trabaja Twiginternamente. Vamos a crear una simple etiqueta set que te permita definir variables simples dentro de una plantilla. Puedes utilizar la etiqueta de la siguiente manera:
{% set name = "value" %}

{{ name }}

{# debe producir value #}

Nota
La etiqueta set es parte de la extensin core y como tal siempre est disponible. La versin integrada es un poco ms potente y de manera predeterminada es compatible con mltiples asignaciones (consulta el captulo Twig para diseadores de plantillas para ms informacin). para definir una nueva etiqueta son necesarios tres pasos:

Definir una clase para analizar segmentos (responsable de analizar el cdigo de la plantilla); Definir una clase Nodo (responsable de convertir el cdigo analizado a PHP); Registrar la etiqueta.

Registrando una nueva etiqueta

Agregar una etiqueta es tan simple como una llamada al mtodo addTokenParser en la instancia de Twig_Environment:
$twig = new Twig_Environment($loader); $twig->addTokenParser(new Project_Set_TokenParser());

Definiendo un analizador de fragmentos

Ahora, vamos a ver el cdigo real de esta clase:

class Project_Set_TokenParser extends Twig_TokenParser { public function parse(Twig_Token $token) { $lineno = $token->getLine(); $name = $this->parser ->getStream() ->expect(Twig_Token::NAME_TYPE) ->getValue(); $this->parser->getExpressionParser() ->expect(Twig_Token::OPERATOR_TYPE, '='); $value = $this->parser ->getExpressionParser() ->parseExpression();

$this->parser->getStream() ->expect(Twig_Token::BLOCK_END_TYPE);

return new Project_Set_Node( $name, $value, $lineno, $this->getTag() ); }

public function getTag()

{ return 'set'; } }

El mtodo getTag() debe devolver la etiqueta que queremos analizar, aqu set. El mtodo parse() se invoca cada vez que el analizador encuentra una etiqueta set. Este debe devolver una instancia de Twig_Node que representa el nodo (la llamada para la creacin del Project_Set_Node se explica en la siguiente seccin). El proceso de anlisis se simplifica gracias a un montn de mtodos que se pueden llamar desde el fragmento del flujo ($this->parser->getStream()):
getCurrent(): Obtiene el segmento actual del flujo. next(): Mueve al siguiente segmento en la secuencia, pero devuelve el antiguo. test($type), test($value) o test($type, $value): Determina si el segmento

actual es de un tipo o valor particular (o ambos). El valor puede ser un arreglo de varios posibles valores.
expect($type[, $value[, $message]]): Si el segmento actual no es del tipo/valor

dado lanza un error de sintaxis. De lo contrario, si el tipo y valor son correctos, devuelve el segmento y mueve el flujo al siguiente segmento.
look(): Busca el siguiente segmento sin consumirlo.

Las expresiones de anlisis se llevan a cabo llamando a parseExpression() como lo hicimos para la etiqueta set.

Truco
Leer las clases TokenParser existentes es la mejor manera de aprender todos los detalles esenciales del proceso de anlisis.

Definiendo un nodo
La clase Project_Set_Node en s misma es bastante simple:

class Project_Set_Node extends Twig_Node { public function __construct( $name, Twig_Node_Expression $value, $lineno, $tag = null ) { parent::__construct( array( 'value' => $value ), array( 'name' => $name ), $lineno, $tag ); }

public function compile(Twig_Compiler $compiler) { $compiler ->addDebugInfo($this) ->write('$context[\''.$this->getAttribute('name').'\'] = ') ->subcompile($this->getNode('value')) ->raw(";\n") ; } }

El compilador implementa una interfaz fluida y proporciona mtodos que ayudan a los desarrolladores a generar cdigo PHP hermoso y fcil de leer:
subcompile(): Compila un nodo. raw(): Escribe tal cual la cadena dada. write(): Escribe la cadena dada aadiendo sangra al principio de cada lnea. string(): Escribe una cadena entre comillas. repr(): Escribe una representacin PHP de un valor dado

(consultaTwig_Node_For para un ejemplo real).

addDebugInfo(): Agrega como comentario la lnea del archivo de plantilla

original relacionado con el nodo actual.

indent(): Aplica sangras al cdigo generado (consulta Twig_Node_Block para

un ejemplo real).
outdent(): Quita la sangra al cdigo generado (consulta Twig_Node_Block para

un ejemplo real).

Creando una extensin

La principal motivacin para escribir una extensin es mover el cdigo usado frecuentemente a una clase reutilizable como agregar apoyo para la internacionalizacin. Una extensin puede definir etiquetas, filtros, pruebas, operadores, variables globales, funciones y visitantes de nodo. La creacin de una extensin tambin hace una mejor separacin del cdigo que se ejecuta en tiempo de compilacin y el cdigo necesario en tiempo de ejecucin. Por lo tanto, hace que tu cdigo sea ms rpido. La mayora de las veces, es til crear una extensin para tu proyecto, para acoger todas las etiquetas y filtros especficos que deseas agregar a Twig.

Truco
Al empacar tu cdigo en una extensin, Twig es lo suficientemente inteligente como para volver a compilar tus plantillas cada vez que les hagas algn cambio (cuandoauto_reload est habilitado).

Nota

Antes de escribir tus propias extensiones, chale un vistazo al repositorio de extensiones oficial de Twig: http://github.com/fabpot/Twig-extensions. Una extensin es una clase que implementa la siguiente interfaz:
interface Twig_ExtensionInterface { /** * Inicia el entorno en tiempo de ejecucin. * * Aqu es donde puedes cargar algn archivo que contenga funciones * de filtro, por ejemplo. * * @param Twig_Environment $environment La instancia actual de * */ function initRuntime(Twig_Environment $environment); Twig_Environment

/** * Devuelve instancias del analizador de segmentos para aadirlos a * la lista existente. * * @return array Un arreglo de instancias Twig_TokenParserInterface * */ function getTokenParsers(); o Twig_TokenParserBrokerInterface

/**

* Devuelve instancias del visitante de nodos para aadirlas a la * lista existente. * * @return array Un arreglo de instancias de * */ function getNodeVisitors(); Twig_NodeVisitorInterface

/** * Devuelve una lista de filtros para aadirla a la lista * existente. * * @return array Un arreglo de filtros */ function getFilters();

/** * Devuelve una lista de pruebas para aadirla a la lista * existente. * * @return array Un arreglo de pruebas */ function getTests();

/** * Devuelve una lista de funciones para aadirla a la lista

* existente. * * @return array Un arreglo de funciones */ function getFunctions();

/** * Devuelve una lista de operadores para aadirla a la lista * existente. * * @return array Un arreglo de operadores */ function getOperators();

/** * Devuelve una lista de variables globales para aadirla a la * lista existente. * * @return array Un arreglo de variables globales */ function getGlobals();

/** * Devuelve el nombre de la extensin. * * @return string El nombre de la extensin

*/ function getName(); }

Para mantener tu clase de extensin limpia y ordenada, puedes heredar de la claseTwig_Extension incorporada en lugar de implementar toda la interfaz. De esta forma, slo tienes que implementar el mtodo getName() como el que proporcionan las implementaciones vacas de Twig_Extension para todos los otros mtodos. El mtodo getName() debe devolver un identificador nico para tu extensin. Ahora, con esta informacin en mente, vamos a crear la extensin ms bsica posible:
class Project_Twig_Extension extends Twig_Extension { public function getName() { return 'project'; } }

Nota
Por supuesto, esta extensin no hace nada por ahora. Vamos a personalizarla en las siguientes secciones. A Twig no le importa dnde guardas tu extensin en el sistema de archivos, puesto que todas las extensiones se deben registrar explcitamente para estar disponibles en tus plantillas. Puedes registrar una extensin con el mtodo addExtension() en tu objetoEnvironment principal:
$twig = new Twig_Environment($loader);

$twig->addExtension(new Project_Twig_Extension());

Por supuesto, tienes que cargar primero el archivo de la extensin, ya sea utilizandorequire_once() o con un cargador automtico (consulta la seccinspl_autoload_register()).

Truco
Las extensiones integradas son grandes ejemplos de cmo trabajan las extensiones.

Globales
Puedes registrar las variables globales en una extensin va el mtodo getGlobals():
class Project_Twig_Extension extends Twig_Extension { public function getGlobals() { return array( 'text' => new Text(), ); }

// ... }

Funciones
Puedes registrar funciones en una extensin va el mtodo getFunctions():
class Project_Twig_Extension extends Twig_Extension

{ public function getFunctions() { return array( new Twig_SimpleFunction('lipsum', 'generate_lipsum'), ); }

// ... }

Filtros
Para agregar un filtro a una extensin, es necesario sustituir el mtodo getFilters(). Este mtodo debe devolver un arreglo de filtros para aadir al entorno Twig:
class Project_Twig_Extension extends Twig_Extension { public function getFilters() { return array( new Twig_SimpleFilter('rot13', 'str_rot13'), ); }

// ... }

Etiquetas
Puedes agregar una etiqueta en una extensin reemplazando el mtodogetTokenParsers(). Este mtodo debe devolver un arreglo de etiquetas para aadir al entorno Twig:
class Project_Twig_Extension extends Twig_Extension { public function getTokenParsers() { return array(new Project_Set_TokenParser()); }

// ... }

En el cdigo anterior, hemos aadido una sola etiqueta nueva, definida por la claseProject_Set_TokenParser. La clase Project_Set_TokenParser es responsable de analizar la etiqueta y compilarla a PHP.

Operadores
El mtodo getOperators() te permite aadir nuevos operadores. Aqu tienes cmo aadir los operadores !, || y &&:
class Project_Twig_Extension extends Twig_Extension { public function getOperators() { return array( array( '!' => array( 'precedence' => 50,

'class' => 'Twig_Node_Expression_Unary_Not' ), ), array( '||' => array( 'precedence' => 10, 'class' => 'Twig_Node_Expression_Binary_Or', 'associativity' => Twig_ExpressionParser::OPERATOR_LEFT ), '&&' => array( 'precedence' => 15, 'class' => 'Twig_Node_Expression_Binary_And', 'associativity' => Twig_ExpressionParser::OPERATOR_LEFT ), ), ); }

// ... }

Pruebas
El mtodo getTests() te permite aadir funciones de prueba:

class Project_Twig_Extension extends Twig_Extension { public function getTests() { return array( new Twig_SimpleTest('even', 'twig_test_even'), ); }

// ... }

Sobrecargando
Para sobrecargar un filtro, prueba, operador, variable global o funcin existente, defnelo de nuevo tan tarde como sea posible:
$twig = new Twig_Environment($loader); $twig->addFilter(new Twig_SimpleFilter('date', function ($timestamp, $format = 'F j, Y H:i') { // hace algo diferente que el filtro date integrado }));

Aqu, se sobrecarg el filtro date integrado con uno personalizado. Esto tambin trabaja con una extensin:
class MyCoreExtension extends Twig_Extension { public function getFilters()

{ return array( new Twig_SimpleFilter('date', array($this, 'dateFilter')), ); }

public function dateFilter($timestamp, $format = 'F j, Y H:i') { // hace algo diferente que el filtro date integrado }

public function getName() { return 'project'; } }

$twig = new Twig_Environment($loader); $twig->addExtension(new MyCoreExtension());

Prudencia
Ten en cuenta que no es recomendable sobrecargar elementos integrados en Twigpuesto que puede ser confuso.

Probando una extensin

Pruebas funcionales
Puedes crear pruebas funcionales para extensiones simplemente creando la siguiente estructura de archivos en tu directorio de pruebas (test):
Fixtures/ filters/ foo.test bar.test functions/ foo.test bar.test tags/ foo.test bar.test IntegrationTest.php

El archivo IntegrationTest.php debe tener la siguiente apariencia:

class Project_Tests_IntegrationTest extends Twig_Test_IntegrationTestCase { public function getExtensions() { return array( new Project_Twig_Extension1(), new Project_Twig_Extension2(), );

public function getFixturesDir() { return dirname(__FILE__).'/Fixtures/'; } }

Los accesorios de ejemplo se pueden encontrar dentro del directorio del repositorio de Twig tests/Twig/Fixtures.

Pruebas de nodo
Probar los visitantes de nodo puede ser complejo, as que extiende tus casos de prueba de Twig_Test_NodeTestCase. Puedes encontrar ejemplos en el directorio del repositorio de Twig tests/Twig/Node.

Twig por dentro

Twig es muy extensible y lo puedes mejorar fcilmente. Ten en cuenta que probablemente deberas tratar de crear una extensin antes de sumergirte en el ncleo, puesto que la mayora de las caractersticas y mejoras se pueden hacer con extensiones. Este captulo tambin es til para personas que quieren entender cmo funciona Twig bajo el cap.

Cmo funciona Twig?

La reproduccin de una plantilla Twig se puede resumir en cuatro pasos fundamentales:

Cargar la plantilla: Si la plantilla ya est compilada, la carga y va al pasoevaluacin, de lo contrario: o En primer lugar, el analizador lxico reduce el cdigo fuente de la plantilla a pequeas piezas para facilitar su procesamiento;

A continuacin, el analizador convierte el flujo del segmento en un rbol de nodos significativo (el rbol de sintaxis abstracta);

Eventualmente, el compilador transforma el rbol de sintaxis abstracta en cdigo PHP;

Evaluar la plantilla: Bsicamente significa llamar al mtodo display() de la plantilla compilada adjuntando el contexto.

El analizador lxico
El analizador lxico acorta el cdigo fuente de una plantilla hasta una secuencia de smbolos (cada smbolo es una instancia de Twig_Token, y la secuencia es una instancia de Twig_TokenStream). El analizador lxico por omisin reconoce 13 diferentes tipos de smbolos:
Twig_Token::BLOCK_START_TYPE, Twig_Token::BLOCK_END_TYPE:

Delimitadores para bloques ({% %}) Twig_Token::VAR_START_TYPE, Twig_Token::VAR_END_TYPE: Delimitadores para variables ({{ }})

Twig_Token::TEXT_TYPE: Un texto fuera de una expresin; Twig_Token::NAME_TYPE: Un nombre en una expresin; Twig_Token::NUMBER_TYPE: Un nmero en una expresin; Twig_Token::STRING_TYPE: Una cadena en una expresin; Twig_Token::OPERATOR_TYPE: Un operador; Twig_Token::PUNCTUATION_TYPE: Un signo de puntuacion; Twig_Token::INTERPOLATION_START_TYPE, Twig_Token::INTERPOLATION_EN D_TYPE (a partir de la ramita 1,5): Los delimitadores para la interpolacin de

cadenas;
Twig_Token::EOF_TYPE: Extremos de la plantilla.

Puedes convertir manualmente un cdigo fuente en una secuencia de segmentos llamando al mtodo tokenize() de un entorno:
$stream = $twig->tokenize($source, $identifier);

Dado que el flujo tiene un mtodo __toString(), puedes tener una representacin textual del mismo haciendo eco del objeto:
echo $stream."\n";

Aqu est la salida para la plantilla Hello {{ name }}:

TEXT_TYPE(Hello ) VAR_START_TYPE() NAME_TYPE(name) VAR_END_TYPE() EOF_TYPE()

Nota
Puedes cambiar el analizador lxico predeterminado usado por Twig (Twig_Lexer) llamando al mtodo setLexer():
$twig->setLexer($lexer);

El analizador sintctico
El analizador convierte la secuencia de smbolos en un ASA (rbol de sintaxis abstracta), o un rbol de nodos (una instancia de Twig_Node_Module). La extensin del ncleo define los nodos bsicos como: for, if, ... y la expresin nodos. Puedes convertir manualmente una secuencia de smbolos en un nodo del rbol llamando al mtodo parse() de un entorno:
$nodes = $twig->parse($stream);

Al hacer eco del objeto nodo te da una buena representacin del rbol:
echo $nodes."\n";

Aqu est la salida para la plantilla Hello {{ name }}:

Twig_Node_Module( Twig_Node_Text(Hello ) Twig_Node_Print( Twig_Node_Expression_Name(name) ) )

Nota
Tambin puedes cambiar el analizador predeterminado (Twig_TokenParser) llamando al mtodo setParser():
$twig->setParser($analizador);

El compilador
El ltimo paso lo lleva a cabo el compilador. Este necesita un rbol de nodos como entrada y genera cdigo PHP que puedes emplear para ejecutar las plantillas en tiempo de ejecucin. Puedes llamar al compilador manualmente con el mtodo compile() de un entorno:
$php = $twig->compile($nodes);

El mtodo compile() devuelve el cdigo fuente PHP que representa al nodo. La plantilla generada por un patrn Hello {{ name }} es la siguiente (la salida real puede diferir dependiendo de la versin de Twig que ests usando):
/* Hello {{ name }} */ class __TwigTemplate_1121b6f109fe93ebe8c6e22e3712bceb extends Twig_Template {

protected function doDisplay(array $context, array $blocks = array()) { // line 1 echo "Hello "; echo twig_escape_filter($this->env, $this->getContext($context, "name"), "ndex", null, true); }

// algn cdigo adicional }

Nota
En cuanto a los analizadores lxico y sintctico, el compilador predeterminado (Twig_Compiler) se puede cambiar mediante una llamada al mtodo setCompiler():
$twig->setCompiler($compilador);

Recetas
Haciendo un diseo condicional
Trabajar con Ajax significa que el mismo contenido a veces se muestra tal cual, y, a veces se decora con un diseo. Dado que el nombre del diseo de las plantillas Twigpuede ser cualquier expresin vlida, puedes pasar una variable que evale a truecuando se hace la peticin a travs de Ajax y elegir el diseo en consecuencia:
{% extends request.ajax ? "base_ajax.html" : "base.html" %}

{% block content %}

Este es el contenido a mostrar. {% endblock %}

Haciendo una inclusin dinmica

Cuando incluyes una plantilla, su nombre no tiene por qu ser una cadena. Por ejemplo, el nombre puede depender del valor de una variable:
{% include var ~ '_foo.html' %}

Si var evala como index, se reproducir la plantilla index_foo.html. De hecho, el nombre de la plantilla puede ser cualquier expresin vlida, como la siguiente:
{% include var|default('index') ~ '_foo.html' %}

Sustituyendo una plantilla que adems se extiende a s misma

Puedes personalizar una plantilla de dos formas diferentes:

Herencia: Una plantilla extiende a una plantilla padre y sustituye algunos bloques; Sustitucin: Si utilizas el cargador del sistema de archivos, Twig carga la primera plantilla que encuentre en una lista de directorios configurados; una plantilla que se encuentra en un directorio sustituye a otra de un directorio ms en la lista.

Pero, cmo se combinan las dos cosas?: sustituir una plantilla que tambin se extiende a s misma (tambin conocida como una plantilla en un directorio ms en la lista) Digamos que tus plantillas se cargan tanto desde .../templates/mysite como de.../templates/default, en este orden. La plantilla page.twig almacenada en../templates/default es la siguiente:

{# page.twig #} {% extends "base.twig" %}

{% block content %} {% endblock %}

Puedes sustituir esta plantilla poniendo un archivo con el mismo nombre en.../templates/mysite. Y si deseas ampliar la plantilla original, podras tener la tentacin de escribir lo siguiente:
{# page.twig en .../templates/mysite #} {% extends "page.twig" %} {# desde .../templates/default #}

Por supuesto, esto no funcionar debido a que Twig siempre carga la plantilla desde.../templates/mysite. Resulta que es posible conseguir que esto funcione, aadiendo el directorio adecuado al final de tus directorios de plantilla, el cual es el padre de todos los otros directorios: .../templates en nuestro caso. Esto tiene el efecto de hacer que cada archivo de plantilla dentro de nuestro sistema sea direccionable unvocamente. La mayora de las veces utilizars rutas normales, pero en el caso especial de querer extender una plantilla con una versin que se redefine a s misma podemos referirnos a la ruta completa del padre, sin ambigedades, en la etiqueta extends de la plantilla:
{# page.twig en .../templates/mysite #} {% extends "default/page.twig" %} {# from .../templates #}

Nota
Esta receta est inspirada en la pgina Extendiendo plantillas del wiki de Django: La puedes ver aqu

Personalizando la sintaxis
Twig te permite personalizar alguna sintaxis de los delimitadores de bloque. No se recomienda usar esta caracterstica puesto que las plantillas sern vinculadas con tu sintaxis personalizada. Sin embargo, para proyectos especficos, puede tener sentido cambiar los valores predeterminados. Para cambiar los delimitadores de bloque, necesitas crear tu propio objeto analizador sintctico (o lexer):
$twig = new Twig_Environment();

$lexer = new Twig_Lexer($twig, array( 'tag_comment' => array('{#', '#}'), 'tag_block' => array('{%', '%}'),

'tag_variable' => array('{{', '}}'), )); $twig->setLexer($lexer);

Estos son algunos ejemplos de configuracin que simulan la sintaxis de algunos otros motores de plantilla:
// sintaxis erb de Ruby $lexer = new Twig_Lexer($twig, array( 'tag_comment' => array('<%#', '%>'), 'tag_block' => array('<%', '%>'),

'tag_variable' => array('<%=', '%>'), ));

// sintaxis de comentarios SGML $lexer = new Twig_Lexer($twig, array(

'tag_comment' => array('<!--#', '-->'), 'tag_block' => array('<!--', '-->'),

'tag_variable' => array('${', '}'), ));

// como Smarty $lexer = new Twig_Lexer($twig, array( 'tag_comment' => array('{*', '*}'), 'tag_block' => array('{', '}'),

'tag_variable' => array('{$', '}'), ));

Usando propiedades dinmicas de objetos

Cuando Twig encuentra una variable como articulo.titulo, trata de encontrar una propiedad pblica titulo en el objeto articulo. Tambin funciona si la propiedad no existe, pero ms bien est definida de forma dinmica gracias a la magia del mtodo __get(); slo tienes que implementar tambin el mtodo mgico __isset(), como muestra el siguiente fragmento de cdigo:
class Article { public function __get($name) { if ('title' == $name) { return 'The title'; }

// lanza algn tipo de error }

public function __isset($name) { if ('title' == $name) { return true; }

return false; } }

Accediendo al contexto del padre en bucles anidados

A veces, cuando utilizas bucles anidados, necesitas acceder al contexto del padre. El contexto del padre siempre es accesible a travs de la variable loop.parent. Por ejemplo, si tienes los siguientes datos de plantilla:
$datos = array( 'temas' => array( 'tema1' => array('Mensaje 1 del tema 1', 'Mensaje 2 del tema 1'), 'tema2' => array('Mensaje 1 del tema 2', 'Mensaje 2 del tema 2'), ), );

Y la siguiente plantilla para mostrar todos los mensajes en todos los temas:

{% for topic, messages in topics %} * {{ loop.index }}: {{ topic }} {% for message in messages %} - {{ loop.parent.loop.index }}.{{ loop.index }}: {{ message }} {% endfor %} {% endfor %}

Reproducir algo similar a:

* 1: topic1 - 1.1: The message 1 of topic 1 - 1.2: The message 2 of topic 1 * 2: topic2 - 2.1: The message 1 of topic 2 - 2.2: The message 2 of topic 2

En el bucle interno, utilizamos la variable loop.parent para acceder al contexto externo. As, el ndice del tema actual definido en el exterior del bucle es accesible a travs de la variable loop.parent.loop.index.

Definiendo al vuelo funciones y filtros indefinidos

Cuando una funcin (o un filtro) no est definido, de manera predeterminada Twiglanza una excepcin Twig_Error_Syntax. Sin embargo, tambin puede invocar unaretrollamada (cualquier PHP vlido que se pueda ejecutar) la cual debe devolver una funcin (o un filtro). Para filtros, registra las retrollamadas con registerUndefinedFilterCallback(). Para funciones, usa registerUndefinedFunctionCallback():
// Autoregistra todas las funciones nativas de PHP como funciones Twig

// no intentes esto en casa, ya que no es seguro en absoluto! $twig->registerUndefinedFunctionCallback(function ($name) { if (function_exists($name)) { return new Twig_Function_Function($name); }

return false; });

Si el ejecutable no es capaz de devolver una funcin vlida (o filtro), deber devolverfalse. Si registras ms de una retrollamada, Twig la llamar a su vez hasta que una no devuelva false.

Truco
Debido a que la resolucin de funciones y filtros se realiza durante la compilacin, no hay ninguna sobrecarga cuando registras estas retrollamadas.

Validando la sintaxis de la plantilla

Cuando el cdigo de plantilla lo proporciona un tercero (a travs de una interfaz web, por ejemplo), podra ser interesante validar la sintaxis de la plantilla antes de guardarla. Si el cdigo de la plantilla se almacena en una variable $template, as es cmo lo puedes hacer:
try { $twig->parse($twig->tokenize($template));

// $template es vlida } catch (Twig_Error_Syntax $e) { // $template contiene uno o ms errores de sintaxis

Si iteras sobre una serie de archivos, puedes suministrar el nombre de archivo al mtodo tokenize() para tener el nombre de archivo en el mensaje de la excepcin:
foreach ($files as $file) { try { $twig->parse($twig->tokenize($template, $file));

// la $template es vlida } catch (Twig_Error_Syntax $e) { // la $template contiene uno o ms errores de sintaxis } }

Nota
Este mtodo no atrapa ninguna violacin de las polticas del recinto de seguridad porque la poltica se aplica durante la reproduccin de la plantilla (debido a queTwig necesita el contexto para comprobar los mtodos permitidos en los objetos).

Actualizando plantillas modificadas cuando APCest habilitado y apc.stat=0

Cuando utilizas APC con apc.stat establecido en 0 y est habilitada la memorizacin en cach de Twig, borra la cach de la plantilla que no va a actualizar la memoria cach APC. Para evitar esto, puedes extender Twig_Environment y forzar la actualizacin de la cach APC cuando Twig reescriba la memoria cach:

class Twig_Environment_APC extends Twig_Environment { protected function writeCacheFile($file, $content) { parent::writeCacheFile($file, $content);

// Archivo memorizado y compilado a bytecode apc_compile_file($file); } }

Reutilizando el estado de un visitante de nodo

Al asociar un visitante a una instancia de Twig_Environment, Twig lo utilizar para visitar todas las plantillas que compile. Si necesitas mantener cierta informacin de estado, probablemente desees restablecerla cuando visites una nueva plantilla. Lo puedes lograr fcilmente con el siguiente cdigo:
protected $someTemplateState = array();

public function enterNode(Twig_NodeInterface $node, Twig_Environment $env) { if ($node instanceof Twig_Node_Module) { Restablece el estado puesto que estamos entrando en una // nueva plantilla $this->someTemplateState = array();

// ...

return $node; }

Usando el nombre de la plantilla para determinar la estrategia de escape predeterminada

Nuevo en la versin 1.8: Esta receta requiere Twig 1.8 o posterior. La opcin autoescape determina la estrategia de escape predefinida a utilizar cuando no se aplica escape a una variable. Cuando utilizas Twig para generar en su mayora archivos HTML, la puedes establecer a html y cambiarla explcitamente a js cuando tengas algunos archivos JavaScript dinmicos gracias a la etiqueta autoescape:
{% autoescape 'js' %} ... algn JS ... {% endautoescape %}

Pero si tienes muchos archivos HTML y JS, y si tus nombres de plantilla siguen algunas convenciones, en su lugar puedes determinar la estrategia de escape a usar en funcin del nombre de la plantilla. Digamos que tus nombres de plantilla siempre terminan con .html para archivos HTML y .js para los de JavaScript, aqu tienes cmo lo puedes configurar en Twig:
class TwigEscapingGuesser { function guess($filename)

{ // obtiene el formato $format = substr($filename, strrpos($filename, '.') + 1);

switch ($format) { case 'js': return 'js'; case 'css': return 'css'; case 'html': default: return 'html'; } } }

$loader = new Twig_Loader_Filesystem('/ruta/a/templates'); $twig = new Twig_Environment($loader, array( 'autoescape' => array(new TwigEscapingGuesser(), 'guess'), ));

Esta estrategia dinmica no incurre en ningn tipo de sobrecarga en tiempo de ejecucin puesto que el autoescape se hace en tiempo de compilacin.

Usando una base de datos para almacenar plantillas

Si ests desarrollando un CMS, las plantillas normalmente se almacenan en una base de datos. Esta receta te da un sencillo cargador de plantilla PDO que puedes utilizar como punto de partida para el tuyo. Primero, crea una base de datos SQLite3 provisional en memoria con la cual trabajar:
$dbh = new PDO('sqlite::memory:'); $dbh->exec('CREATE TABLE templates (name STRING, source STRING, last_modified INTEGER)'); $base = '{% block content %}{% endblock %}'; $index = ' {% extends "base.twig" %} {% block content %}Hello {{ name }}{% endblock %} '; $now = time(); $dbh->exec("INSERT INTO templates (name, source, last_modified) VALUES ('base.twig', '$base', $now)"); $dbh->exec("INSERT INTO templates (name, source, last_modified) VALUES ('index.twig', '$index', $now)");

Creaste una sencilla tabla templates que hospeda dos plantillas: base.twig eindex.twig. Ahora, define un cargador capaz de utilizar esa base de datos:
class DatabaseTwigLoader implements Twig_LoaderInterface, Twig_ExistsLoaderInterface { protected $dbh;

public function __construct(PDO $dbh) { $this->dbh = $dbh; }

public function getSource($name) { if (false === $source = $this->getValue('source', $name)) { throw new Twig_Error_Loader(sprintf('Template "%s" does not exist.', $name)); }

return $source; }

// Twig_ExistsLoaderInterface a partir de Twig 1.11 public function exists($name) { return $name === $this->getValue('name', $name); }

public function getCacheKey($name) { return $name; }

public function isFresh($name, $time) { if (false === $lastModified = $this->getValue('last_modified', $name)) { return false; }

return $lastModified <= $time; }

protected function getValue($column, $name) { $sth = $this->dbh->prepare('SELECT '.$column.' FROM templates WHERE name = :name'); $sth->execute(array(':name' => (string) $name));

return $sth->fetchColumn(); } }

Finalmente, aqu tienes un ejemplo de cmo la puedes utilizar:

$loader = new DatabaseTwigLoader($dbh); $twig = new Twig_Environment($loader);

echo $twig->render('index.twig', array('name' => 'Fabien'));

Usando diferentes fuentes de plantillas

Esta receta es la continuacin de la anterior. Incluso si almacenas plantillas contribuidas en una base de datos, podras querer mantener las plantillas originales/base en el sistema de archivos. Puesto que puedes cargar plantillas desde diferentes fuentes, necesitas utilizar el cargador Twig_Loader_Chain. Como puedes ver en la receta anterior, se refiri la plantilla exactamente de la misma manera que como se hizo con un cargador regular del sistema de archivos. Esta es la clave para poder mezclar plantillas que provienen desde la base de datos, el sistema de archivos, o cualquiera otro cargador: el nombre de la plantilla debera ser un nombre lgico, y no la ruta del sistema de archivos:
$loader1 = new DatabaseTwigLoader($dbh); $loader2 = new Twig_Loader_Array(array( 'base.twig' => '{% block content %}{% endblock %}', )); $loader = new Twig_Loader_Chain(array($loader1, $loader2));

$twig = new Twig_Environment($loader);

echo $twig->render('index.twig', array('name' => 'Fabien'));

Ahora que la Plantilla base.twig est definida en un arreglo cargador, la puedes remover de la base de datos, y todo trabajar como antes.

Estndares de codificacin
Al escribir plantillas Twig, te recomendamos que sigas las siguientes normas de codificacin oficiales:

Deja un espacio (y slo uno) despus de un delimitador inicial ({{, {%, y {#) y antes del final de un delimitador (}}, %}, y #}):
{{ foo }}

{# comentario #} {% if foo %}{% endif %}

Cuando utilices los caracteres de guin junto con el espacio en blanco, no dejes ningn espacio entre este y el delimitador:
{{- foo -}} {#- comentario -#} {%- if foo -%}{%- endif -%}

Deja un espacio (y slo uno) antes y despus de los siguientes operadores: operadores de comparacin (==, !=, <, >, >=, <=), operadores matemticos (+, -,/, *, %, //, **), operadores lgicos (not, and, or), ~, is, in, y el operador ternario (?:):
{{ 1 + 2 }} {{ foo ~ bar }}

{{ true ? true : false }}

Deja un espacio (y slo uno) despus del signo : en hashes (o codificaciones en adelante), y la , en arreglos y codificaciones:
{{ [1, 2, 3] }} {{ {'foo': 'bar'} }}

No dejes ningn espacio despus de un parntesis de apertura y antes de un parntesis de cierre en expresiones:
{{ 1 + (2 * 3) }}

No dejes ningn espacio en blanco antes y despus de los delimitadores de cadena:

{{ 'foo' }}

{{ "foo" }}

No dejes ningn espacio en blanco antes y despus de los siguientes operadores:|, ., .., []:
{{ foo|upper|lower }} {{ user.name }} {{ user[name] }} {% for i in 1..12 %}{% endfor %}

No dejes ningn espacio en blanco antes y despus de los parntesis utilizados en filtros y llamadas a funcin:
{{ foo|default('foo') }} {{ range(1..10) }}

No dejes ningn espacio en blanco antes y despus de la apertura de arreglos y codificaciones:

{{ [1, 2, 3] }} {{ {'foo': 'bar'} }}

Utiliza letras minsculas y guiones bajos en nombres de variables:

{% set foo = 'foo' %} {% set foo_bar = 'foo' %}

Sangra tu cdigo dentro de las etiquetas (usa la misma profundidad que la utilizada en el lenguaje principal del archivo):
{% block foo %} {% if true %} true {% endif %}

{% endblock %}

Etiquetas
for if macro filter set extends block include import from use spaceless autoescape verbatim flush do sandbox embed

for
Recorre cada elemento de una secuencia. Por ejemplo, para mostrar una lista de usuarios provista en una variable llamada usuarios:
<h1>Members</h1>

<ul> {% for user in users %} <li>{{ user.username|e }}</li> {% endfor %} </ul>

Nota
Una secuencia puede ser un arreglo o un objeto que implemente la interfazTraversable. Si necesitas iterar en una secuencia de nmeros, el operador .. es muy til:
{% for i in 0..10 %} * {{ i }} {% endfor %}

El fragmento de cdigo anterior debera imprimir todos los nmeros del 0 al 10. Tambin lo puedes utilizar con letras:
{% for letter in 'a'..'z' %} * {{ letter }} {% endfor %}

El operador .. puede tomar cualquier expresin en ambos lados:

{% for letter in 'a'|upper..'z'|upper %} * {{ letter }} {% endfor %}

La variable loop
Dentro de un bloque de bucle for puedes acceder a algunas variables especiales:

Variable
loop.index loop.index0

Descripcin La iteracin actual del bucle. (indexada en 1) La iteracin actual del bucle. (indexada en 0) El nmero de iteraciones a partir del final del bucle (indexadas en 1) El nmero de iteraciones a partir del final del bucle (indexadas en 0)
True si es la primera iteracin True si es la ltima iteracin

loop.revindex

loop.revindex0

loop.first loop.last loop.length loop.parent

El nmero de elementos en la secuencia El contexto del padre

{% for user in users %} {{ loop.index }} - {{ user.username }} {% endfor %}

Nota
Las variables loop.length, loop.revindex, loop.revindex0 y loop.last nicamente estn disponibles para arreglos PHP, u objetos que implementen la interfazCountable. Tampoco estn disponibles cuando iteras con una condicin. Nuevo en la versin 1.2: La compatibilidad con el modificador if se aadi en Twig1.2.

Aadiendo una condicin

A diferencia de PHP, en un bucle no es posible usar break ni continue. Sin embargo, puedes filtrar la secuencia durante la iteracin, lo cual te permite omitir elementos. En el siguiente ejemplo se omiten todos los usuarios que no estn activos:

<ul> {% for user in users if user.active %} <li>{{ user.username|e }}</li> {% endfor %} </ul>

La ventaja es que la variable especial loop contar correctamente, es decir, sin contar a los usuarios inactivos en la iteracin. Ten en cuenta que las propiedades comoloop.last no estn definidas cuando usas bucles condicionales.

Nota
Usar la variable loop sin la condicin no es recomendable debido a que no llevar a cabo lo que esperas se haga. Por ejemplo, aadir una condicin como loop.index > 4no funcionar puesto que el ndice nicamente se incrementa cuando la condicin es cierta (por lo tanto, la condicin nunca coincidir).

La clusula else
Si no se llev a cabo iteracin debido a que la secuencia est vaca, puedes reproducir un bloque sustituto utilizando else:
<ul> {% for user in users %} <li>{{ user.username|e }}</li> {% else %} <li><em>no user found</em></li> {% endfor %} </ul>

Iterando en las claves

De forma predeterminada, un bucle itera en los valores de la secuencia. Puedes iterar en las claves con el filtro keys:
<h1>Members</h1> <ul> {% for key in users|keys %} <li>{{ key }}</li> {% endfor %} </ul>

Iterando en claves y valores

Tambin puedes acceder tanto a las claves como a los valores:
<h1>Members</h1> <ul> {% for key, user in users %} <li>{{ key }}: {{ user.username|e }}</li> {% endfor %} </ul>

if
La declaracin if en Twig es comparable con las declaraciones if de PHP. En la forma ms simple la puedes usar para probar si una expresin evala a true:
{% if online == false %} <p>Our website is in maintenance mode. Please, come back later.</p>

{% endif %}

Tambin puedes probar si un arreglo no est vaco:

{% if users %} <ul> {% for user in users %} <li>{{ user.username|e }}</li> {% endfor %} </ul> {% endif %}

Nota
Si deseas probar si una variable est definida, usa if usuarios is defined en su lugar. Para ramificacin mltiple puedes utilizar elseif y else como en PHP. All tambin puedes utilizar expresiones ms complejas:
{% if kenny.sick %} Kenny is sick. {% elseif kenny.dead %} You killed Kenny! You bastard!!! {% else %} Kenny looks okay --- so far {% endif %}

macro
Las macros son comparables con funciones en lenguajes de programacin regulares. Son tiles para poner modismos HTML utilizados frecuentemente en elementos reutilizables para no repetirlos.

He aqu un pequeo ejemplo de una macro que reproduce un elemento de formulario:

{% macro input(name, value, type, size) %} <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" /> {% endmacro %}

Las macros se diferencian de las funciones PHP nativas en varias formas:

Los valores predeterminados de los argumentos se definen usando el filtrodefault en el cuerpo de la macro; Los argumentos de una macro siempre son opcionales.

Pero como las funciones de PHP, las macros no tienen acceso a las variables de la plantilla actual.

Truco
Puedes pasar todo el contexto como un argumento usando la variable especial_context. Las macros se pueden definir en cualquier plantilla, y es necesario importarlas, antes de utilizarlas (consulta la etiqueta import para ms informacin):
{% import "formularios.html" as forms %}

La anterior llamada a import importa el archivo formularios.html (el cual puede contener macros solamente, o una plantilla y algunas macros), e importa las funciones como elementos de la variable forms. Entonces puedes llamar a la macro a voluntad:
<p>{{ forms.input('username') }}</p>

<p>{{ forms.input('password', null, 'password') }}</p>

Si hay macros definidas y se usan en la misma plantilla, puedes utilizar la variable especial _self para importarlas:
{% import _self as forms %}

<p>{{ forms.input('username') }}</p>

Advertencia
Cundo defines una macro en la plantilla donde la vas a utilizar, podra ser tentador llamar a la macro directamente va _self.entrada() en vez de importarla; incluso si parece trabajar, este es justo un efecto colateral de la implementacin actual y no trabajar ms en Twig 2.x. Cundo quieras utilizar una macro en otra macro del mismo archivo, necesitas importarla localmente:
{% macro input(name, value, type, size) %} <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" /> {% endmacro %}

{% macro wrapped_input(name, value, type, size) %} {% import _self as forms %}

<div class="field"> {{ forms.input(name, value, type, size) }} </div>

{% endmacro %}

Ver tambin
from, import

filter
Filtrar secciones te permite aplicar filtros Twig regulares en un bloque de datos de la plantilla. Simplemente envuelve el cdigo en el bloque especial filter:
{% filter upper %} Este texto cambia a maysculas {% endfilter %}

Tambin puedes encadenar filtros:

{% filter lower|escape %} <strong>ALGN TEXTO</strong> {% endfilter %}

{# produce "&lt;strong&gt;some text&lt;/strong&gt;" #}

set
Dentro del cdigo de los bloques tambin puedes asignar valores a variables. Las asignaciones utilizan la etiqueta set y puedes tener mltiples destinos:
{% set foo = 'foo' %}

{% set foo = [1, 2] %}

{% set foo = {'foo': 'bar'} %}

{% set foo = 'foo' ~ 'bar' %}

{% set foo, bar = 'foo', 'bar' %}

La etiqueta set tambin se puede usar para capturar trozos de texto:

{% set foo %} <div id="pagination"> ... </div> {% endset %}

Prudencia
Si habilitas el escape automtico, Twig slo tendr en cuenta el contenido seguro al capturar fragmentos de texto.

extends
Puedes utilizar la etiqueta extends para extender una plantilla a partir de otra.

Nota
Al igual que PHP, Twig no admite la herencia mltiple. Por lo tanto slo puedes tener una etiqueta extends por reproduccin. Sin embargo, Twig apoya el reusohorizontal. Vamos a definir una plantilla base, base.html, la cual define el esqueleto de un documento HTML simple:
<!DOCTYPE html> <html> <head>

{% block head %} <link rel="stylesheet" href="style.css" /> <title>{% block title %}{% endblock %} - My Webpage</title> {% endblock %} </head> <body> <div id="content">{% block content %}{% endblock %}</div> <div id="footer"> {% block footer %} &copy; Copyright 2011 by <a href="http://dominio.invalido/"> t </a>. {% endblock %} </div> </body> </html>

En este ejemplo, las etiquetas block definen cuatro bloques que las plantillas descendientes pueden rellenar. Todas las etiquetas block le dicen al motor de plantillas que una plantilla derivada puede sustituir esas porciones de la plantilla.

Plantilla descendiente
Una plantilla hija podra tener este aspecto:
{% extends "base.html" %}

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

{% block head %} {{ parent() }} <style type="text/css"> .important { color: #336699; } </style> {% endblock %} {% block content %} <h1>Index</h1> <p class="important"> Welcome on my awesome homepage. </p> {% endblock %}

Aqu, la clave es la etiqueta extends. Esta le dice al motor de plantillas que esta plantilla extiende otra plantilla. Cuando el sistema de plantillas evala esta plantilla, en primer lugar busca la plantilla padre. La etiqueta extends debe ser la primera etiqueta en la plantilla. Ten en cuenta que debido a que la plantilla heredera no define el bloque footer, en su lugar se utiliza el valor de la plantilla padre. No puedes definir mltiples etiquetas block con el mismo nombre en la misma plantilla. Esta limitacin existe porque una etiqueta de bloque trabaja en ambas direcciones. Es decir, una etiqueta de bloque no slo proporciona un hueco para rellenar sino que tambin define en el padre el contenido que rellena el hueco. Si en una plantilla hubiera dos etiquetas block con nombres similares, la plantilla padre, no sabra cual contenido de entre esos bloques usar. No obstante, si deseas imprimir un bloque varias veces, puedes utilizar la funcinblock():
<title>{% block title %}{% endblock %}</title> <h1>{{ block('title') }}</h1>

{% block body %}{% endblock %}

Bloques padre
Es posible reproducir el contenido del bloque padre usando la funcin parent. Esta devuelve el resultado del bloque padre:
{% block sidebar %} <h3>Table Of Contents</h3> ... {{ parent() }} {% endblock %}

Etiquetas de cierre de bloques nombrados

Twig te permite poner el nombre del bloque despus de la etiqueta para facilitar su lectura:
{% block sidebar %} {% block inner_sidebar %} ... {% endblock inner_sidebar %} {% endblock sidebar %}

Por supuesto, el nombre despus de la palabra endblock debe coincidir con el nombre del bloque.

Bloques anidados y mbito

Los bloques se pueden anidar para diseos ms complejos. Por omisin, los bloques tienen acceso a las variables del mbito externo:
{% for item in seq %}

<li>{% block loop_item %}{{ item }}{% endblock %}</li> {% endfor %}

Atajos de bloque
Para bloques con poco contenido, es posible utilizar una sintaxis abreviada. Las siguientes construcciones hacen exactamente lo mismo:
{% block title %} {{ page_title|title }} {% endblock %} {% block title page_title|title %}

Herencia dinmica
Twig es compatible con la herencia dinmica usando una variable como la plantilla base:
{% extends alguna_var %}

Si la variable se evala como un objeto Twig_Template, Twig la utilizar como la plantilla padre:
// {% extends base %}

$base = $twig->loadTemplate('some_layout_template.twig');

$twig->display('template.twig', array('base' => $base));

Nuevo en la versin 1.2: La posibilidad de pasar un arreglo de plantillas se aadi enTwig 1.2. Tambin puedes proporcionar una lista de plantillas que comprueben su existencia. La primer plantilla existente se utilizar como el padre:

{% extends ['base.html', 'base_layout.html'] %}

Herencia condicional
Gracias a que el nombre para la plantilla padre puede ser cualquier expresin Twig, es posible el mecanismo de herencia condicional:
{% extends standalone ? "minimum.html" : "base.html" %}

En este ejemplo, la plantilla debe extender a la plantilla base minimum.html si la variable standalone evala a true, o de otra manera extiende a base.html.

Cmo trabajan los bloques?

Un bloque proporciona una manera de cambiar ciertas partes de una plantilla al reproducirla, pero de ninguna manera interfiere con la lgica a su alrededor. Toma el siguiente ejemplo que ilustra cmo trabaja un bloque y ms importante, cmo no trabaja:
{# base.twig #}

{% for post in posts %} {% block post %} <h1>{{ post.title }}</h1> <p>{{ post.body }}</p> {% endblock %} {% endfor %}

Si reproduces esta plantilla, el resultado sera exactamente igual con o sin la etiquetablock. El block dentro del bucle for solo es una manera de hacerlo redefinible en una plantilla hija:
{# child.twig #}

{% extends "base.twig" %}

{% block post %} <article> <header>{{ post.title }}</header> <section>{{ post.text }}</section> </article> {% endblock %}

Ahora, al reproducir la plantilla hija, el bucle utilizar el bloque definido en la plantilla hija en vez del definido en la base; La plantilla ejecutada entonces es equivalente a lo siguiente:
{% for post in posts %} <article> <header>{{ post.title }}</header> <section>{{ post.text }}</section> </article> {% endfor %}

Observa otro ejemplo: un bloque incluido dentro de una declaracin if:

{% if posts is empty %} {% block head %} {{ parent() }}

<meta name="robots" content="noindex, follow"> {% endblock head %}

{% endif %}

Contrario a lo que podras pensar, esta plantilla no define un bloque condicionalmente; Slo lo sustituye con una plantilla hija que produce lo que ser dibujado cundo la condicin sea true. Si quieres mostrar el resultado condicionalmente, en su lugar usa lo siguiente:
{% block head %} {{ parent() }}

{% if posts is empty %} <meta name="robots" content="noindex, follow"> {% endif %} {% endblock head %}

block
Los bloques se utilizan para la herencia y actan como marcadores de posicin y reemplazo al mismo tiempo. Estos estn documentados en detalle en la documentacin de la etiqueta extends. Los nombres de bloque deben consistir de caracteres alfanumricos y guiones bajos. Los guiones no estn permitidos.

Ver tambin
block, parent, use, extends

include
La declaracin include inserta una plantilla y devuelve el contenido presentado por ese archivo en el espacio de nombres actual:

{% include 'header.html' %} Body {% include 'footer.html' %}

Las plantillas incluidas tienen acceso a las variables del contexto activo. Si ests utilizando el cargador del sistema de archivos, las plantillas se buscan en la ruta definida por este. Puedes aadir variables adicionales pasndolas despus de la palabra clave with:
{# template.html tendr acceso a las variables del contexto actual y adicionalmente a las proporcionadas #} {% include 'template.html' with {'foo': 'bar'} %}

{% set vars = {'foo': 'bar'} %} {% include 'template.html' with vars %}

Puedes desactivar el acceso al contexto aadiendo la palabra clave only:

{# nicamente la variable foo ser accesible #} {% include 'template.html' with {'foo': 'bar'} only %} {# ninguna variable ser accesible #} {% include 'template.html' only %}

Truco
Cuando incluyes una plantilla creada por un usuario final, debes considerar supervisarla. Ms informacin en el captulo Twig para desarrolladores y en la documentacin de la etiqueta sandbox. El nombre de la plantilla puede ser cualquier expresin Twig vlida:
{% include some_var %} {% include ajax ? 'ajax.html' : 'not_ajax.html' %}

Y si la expresin evala como un objeto Twig_Template, Twig la usar directamente:

// {% include template %}

$template = $twig->loadTemplate('some_template.twig');

$twig->loadTemplate('template.twig') ->display(array('template' => $template));

Nuevo en la versin 1.2: La caracterstica ignore missing se aadi en Twig 1.2. Puedes marcar un include con ignore missing en cuyo caso Twig omitir la declaracin si la plantilla a ignorar no existe. Se tiene que colocar justo despus del nombre de la plantilla. He aqu algunos ejemplos vlidos:
{% include 'sidebar.html' ignore missing %} {% include 'sidebar.html' ignore missing with {'foo': 'bar'} %} {% include 'sidebar.html' ignore missing only %}

Nuevo en la versin 1.2: La posibilidad de pasar un arreglo de plantillas se aadi enTwig 1.2. Tambin puedes proporcionar una lista de plantillas para comprobar su existencia antes de la inclusin. La primer plantilla existente ser incluida:
{% include ['page_detailed.html', 'page.html'] %}

Si se le da ignore missing, caer de nuevo en reproducir nada si ninguna de las plantillas existe, de lo contrario se producir una excepcin.

import
Twig cuenta con el soporte necesario para poner en macros el cdigo usado frecuentemente macros. Estas macros pueden estar en diferentes plantillas y se importan desde all.

Hay dos formas de importar plantillas. Puedes importar la plantilla completa en una variable o solicitar macros especficas de ella. Imagina que tienes un mdulo auxiliar que reproduce formularios (llamadoformularios.html):
{% macro input(name, value, type, size) %} <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" /> {% endmacro %}

{% macro textarea(name, value, rows) %} <textarea name="{{ name }}" rows="{{ rows|default(10) }}" cols="{{ cols|default(40) }}"> {{ value|e }} </textarea> {% endmacro %}

La forma ms fcil y flexible es importar todo el mdulo en una variable. De esa manera puedes acceder a los atributos:
{% import 'formularios.html' as forms %}

<dl> <dt>Username</dt> <dd>{{ forms.input('username') }}</dd> <dt>Password</dt>

<dd>{{ forms.input('password', null, 'password') }}</dd> </dl> <p>{{ forms.textarea('comentario') }}</p>

Alternativamente, puedes importar nombres desde la plantilla al espacio de nombres actual:

{% from 'formularios.html' import input as campo_input, textarea %}

<dl> <dt>Username</dt> <dd>{{ input_field('username') }}</dd> <dt>Password</dt> <dd>{{ input_field('password', '', 'password') }}</dd> </dl> <p>{{ textarea('comment') }}</p>

Truco
Para importar macros desde el archivo actual, usa la variable especial _self para la fuente.

Ver tambin
macro, from

from
Las etiquetas from importan nombres de macro al espacio de nombres actual. La etiqueta est documentada en detalle en la documentacin de la etiqueta import.

Ver tambin
macro, import

use
Nuevo en la versin 1.1: La reutilizacin horizontal se aadi en Twig 1.1.

Nota
La reutilizacin horizontal es una caracterstica avanzada de Twig que casi nunca es necesaria en plantillas regulares. La utilizan principalmente proyectos que tienen que reutilizar bloques de plantilla sin utilizar herencia. La herencia de plantillas es una de las ms poderosas caractersticas de Twig, pero est limitada a herencia simple; una plantilla slo puede extender a una plantilla ms. Esta limitacin facilita el entendimiento y depuracin de la herencia de plantillas:
{% extends "base.html" %}

{% block title %}{% endblock %} {% block content %}{% endblock %}

La reutilizacin horizontal es una forma de conseguir el mismo objetivo que la herencia mltiple, pero sin la complejidad asociada:
{% extends "base.html" %}

{% use "bloques.html" %}

{% block title %}{% endblock %} {% block content %}{% endblock %}

La declaracin use dice a Twig que importe los bloques definidos en bloques.html a la plantilla actual (es como las macros, pero para bloques):
{# bloques.html #} {% block sidebar %}{% endblock %}

En este ejemplo, la declaracin use importa la declaracin del bloque sidebar en la plantilla principal. El cdigo en su mayora es equivalente a lo siguiente (los bloques importados no se generan automticamente):
{% extends "base.html" %}

{% block sidebar %}{% endblock %} {% block title %}{% endblock %} {% block content %}{% endblock %}

Nota
La etiqueta use slo importa una plantilla si esta:

no extiende a otra plantilla no define macros, y si el cuerpo est vaco. Pero puedes usar otras plantillas.

Nota
Debido a que las declaraciones use se resuelven independientemente del contexto pasado a la plantilla, la referencia de la plantilla no puede ser una expresin. La plantilla principal tambin puede sustituir cualquier bloque importado. Si la plantilla ya define el bloque sidebar, entonces, se ignora el definido en bloques.html. Para evitar conflictos de nombre, puedes cambiar el nombre de los bloques importados:
{% extends "base.html" %}

{% use "bloques.html" with sidebar as base_sidebar %}

{% block sidebar %}{% endblock %} {% block title %}{% endblock %} {% block content %}{% endblock %}

Nuevo en la versin 1.3: El apoyo a parent() se aadi en Twig 1.3. La funcin parent() determina automticamente el rbol de herencia correcto, por lo tanto lo puedes utilizar cuando reemplaces un bloque definido en una plantilla importada:
{% extends "base.html" %}

{% use "bloques.html" %}

{% block sidebar %} {{ parent() }} {% endblock %}

{% block title %}{% endblock %} {% block content %}{% endblock %}

En este ejemplo, el parent() correctamente llama al bloque sidebar de la plantillablocks.html.

Truco
En Twig 1.2, el cambio de nombre te permite simular la herencia llamando al bloque padre:
{% extends "base.html" %}

{% use "bloques.html" with sidebar as parent_sidebar %}

{% block sidebar %} {{ block('parent_sidebar') }} {% endblock %}

Nota
Puedes utilizar tantas instrucciones use como quieras en cualquier plantilla determinada. Si dos plantillas importadas definen el mismo bloque, la ltima gana.

spaceless
Usa la etiqueta spaceless para eliminar espacios en blanco entre las etiquetas HTML, no espacios en blanco en las etiquetas HTML o en el texto simple:
{% spaceless %} <div> <strong>foo</strong> </div> {% endspaceless %}

{# Producir <div><strong>foo</strong></div> #}

Esta etiqueta no tiene la intencin de optimizar el tamao del contenido HTMLgenerado, sino simplemente eliminar espacios en blanco extra entre las etiquetasHTML para evitar una representacin caprichosa en navegadores bajo determinadas circunstancias.

Truco
Si deseas optimizar el tamao del contenido HTML generado, en su lugar comprime el resultado con gzip.

Truco
Si deseas crear una etiqueta que retire todos los espacios en blanco extra en una cadena HTML, te advertimos que esto no es tan fcil como parece (piensa en etiquetas textarea o pre, por ejemplo). Usar una biblioteca de terceros, como Tidyprobablemente es una mejor idea.

Truco

Para ms informacin sobre el control de los espacios en blanco, lee la seccin dedicada de la documentacin y tambin aprende cmo puedes utilizar el modificador del control de espacios en blanco en tus etiquetas.

autoescape
Ya sea que el escape automtico est habilitado o no, puedes marcar una seccin de una plantilla para que sea escapada o no utilizando la etiqueta autoescape:
{# La siguiente sintaxis trabaja desde Twig 1.8 -- ve abajo las notas para las versiones anteriores #}

{% autoescape %} En este bloque, todo se escapar automticamente usando la estrategia HTML {% endautoescape %}

{% autoescape 'html' %} En este bloque, todo se escapar automticamente usando la estrategia HTML {% endautoescape %}

{% autoescape 'js' %} Todo en este bloque se escapar automticamente con la estrategia de escape js {% endautoescape %}

{% autoescape false %} En este bloque, todo se emitir tal cual {% endautoescape %}

Nota
Antes de Twig 1.8, la sintaxis era distinta:
{% autoescape true %} En este bloque, todo se escapar automticamente usando la estrategia HTML {% endautoescape %}

{% autoescape false %} En este bloque, todo se emitir tal cual {% endautoescape %}

{% autoescape true js %} Todo en este bloque se escapar automticamente usando la estrategia de escape js {% endautoescape %}

Cuando se activa el escape automtico, de manera predeterminada todo ser escapado, salvo los valores marcados explcitamente como seguros. Estos se pueden marcar en la plantilla usando el filtro raw:
{% autoescape %} {{ safe_value|raw }} {% endautoescape %}

Las funciones que devuelven datos de la plantilla (como macros y parent) siempre devuelven marcado seguro.

Nota
Twig es lo suficientemente inteligente como para no escapar un valor que ya fue escapado por el filtro escape.

Nota
El captulo Twig para desarrolladores proporciona ms informacin acerca de cundo y cmo se aplica el escape automtico.

verbatim
Nuevo en la versin 1.12: La etiqueta verbatim se aadi en Twig 1.12 (antes se llamaba raw). La etiqueta verbatim marca secciones como si fuera texto simple que no se debera analizar. Por ejemplo, para poner la sintaxis de Twig como ejemplo en una plantilla puedes utilizar este fragmento:
{% verbatim %} <ul> {% for item in seq %} <li>{{ item }}</li> {% endfor %} </ul> {% endverbatim %}

Nota
La etiqueta verbatim trabaja exactamente en la misma manera que la antigua etiqueta raw, pero se rebautiz para evitar confusin con el filtro raw.

flush
Nuevo en la versin 1.5: La etiqueta flush se aadi en Twig 1.5. La etiqueta flush le dice a Twig que vace el contenido de la memoria intermedia:
{% flush %}

Nota

Internamente, Twig usa la funcin flush de PHP.

do
Nuevo en la versin 1.5: La etiqueta do se agreg en Twig 1.5. La etiqueta do trabaja exactamente como la variable expresin regular ({{ ... }}) solo que no imprime nada:
{% do 1 + 2 %}

sandbox
La etiqueta sandbox se puede utilizar para activar el modo de recinto de seguridad para una plantilla incluida, cuando no est habilitado globalmente el modo de recinto de seguridad para el entorno Twig:
{% sandbox %} {% include 'user.html' %} {% endsandbox %}

Advertencia
La etiqueta sandbox slo est disponible cuando est habilitada la extensin sandbox(ve el captulo Twig para desarrolladores).

Nota
La etiqueta sandbox slo se puede utilizar para procesar en el recinto de seguridad una etiqueta include y no se puede utilizar para proteger una seccin de una plantilla. El siguiente ejemplo no trabajar:
{% sandbox %} {% for i in 1..2 %} {{ i }} {% endfor %} {% endsandbox %}

embed
Nuevo en la versin 1.8: La etiqueta embed se aadi en Twig 1.8. La etiqueta embed combina el comportamiento de include y extends. Esta te permite incluir contenido de otras plantillas, tal cmo lo hace include. Pero tambin te permite reemplazar cualquier bloque definido en la plantilla incluida, como cuando extiendes una plantilla. Piensa en una plantilla integrada como un esqueleto del microdiseo.
{% embed "esqueleto_tentativo.twig" %} {# Estos bloques estn definidos en "esqueleto_tentativo.twig" #} {# Y los sustituimos aqu: {% block left_teaser %} Algn contenido para la caja de prueba izquierda {% endblock %} {% block right_teaser %} Algn contenido para la caja de prueba derecha {% endblock %} {% endembed %} #}

La etiqueta embed lleva la idea de la herencia de plantillas a nivel de fragmentos de contenido. Si bien la herencia de plantillas posibilita los esqueletos de documento, que estn llenos de vida por las plantillas hijas, la etiqueta embed te permite crear esqueletos para las ms pequeas unidades de contenido y reutilizarlas y llenarlas en cualquier lugar que quieras. Debido al caso de uso puede no ser tan obvio, veamos un ejemplo simplificado. Imagina una plantilla base compartida por varias pginas HTML, la cual define un solo bloque llamado contenido:
diseo de pgina

bloque "contenido"

(plantilla hija aqu lleva el contenido)

Algunas pginas (foo y bar) comparten la misma estructura del contenido dos cajas apiladas verticalmente:
diseo de pgina bloque "contenido" bloque "sup"

bloque "inf"

mientras otras pginas (boom y baz) comparten una estructura de contenido diferente dos cajas lado a lado:

 diseo de pgina bloque "contenido"

bloque bloque "izq" "der"

Sin la etiqueta embed, tienes dos maneras de disear tus plantillas:

Crea dos plantillas base intermedias que extiendan a la plantilla del diseo principal: una con cajas apiladas verticalmente usada por las pginas foo y bar y otra con cajas lado a lado para las pginas boom y baz. Integrar el marcado para las cajas sup/inf e izq/der en cada plantilla de pgina directamente.

Estas dos soluciones no se adaptan bien porque cada una tiene un gran inconveniente:

La primer solucin en verdad puede trabajar para este ejemplo simplificado. Pero imagina que aadimos una barra lateral, la cual a su vez contiene diferentes, estructuras de contenido recurrente. Ahora tendramos que crear plantillas base intermedias para todas las combinaciones que produzcan estructuras de contenido y estructura de la barra lateral... y as sucesivamente. La segunda solucin consiste en duplicar cdigo comn con todos sus efectos y consecuencias negativas: cualquier cambio implica encontrar y editar todas las copias afectadas por la estructura, la

correccin se tiene que verificar en cada copia, las copias pueden estar fuera de sincrona por modificaciones descuidadas, etc. En tal situacin, la etiqueta embed viene muy bien. El cdigo del diseo comn puede vivir en una sola plantilla base, y las dos estructuras de contenido diferentes, vamos a llamarlas microdiseos tendremos plantillas separadas, que sern integradas conforme sea necesario: Plantilla de la pgina foo.twig:
{% extends "layout_skeleton.twig" %}

{% block content %} {% embed "vertical_boxes_skeleton.twig" %} {% block top %} Algn contenido para la caja de prueba superior {% endblock %}

{% block bottom %} Algn contenido para la caja de prueba inferior {% endblock %} {% endembed %} {% endblock %}

Y aqu est el cdigo para vertical_boxes_skeleton.twig:

<div class="top_box"> {% block top %} Contenido predefinido para la caja superior {% endblock %} </div>

<div class="bottom_box"> {% block bottom %} Contenido predefinido para la caja inferior {% endblock %} </div>

El objetivo de la plantilla vertical_boxes_skeleton.twig es el de eliminar el marcadoHTML para las cajas. La etiqueta embed toma exactamente los mismos argumentos que la etiqueta include:
{% embed "base" with {'foo': 'bar'} %} ... {% endembed %}

{% embed "base" with {'foo': 'bar'} only %} ... {% endembed %}

{% embed "base" ignore missing %} ... {% endembed %}

Advertencia
Debido a que las plantillas integradas no tienen nombres, las estrategias de autoescape basadas en el nombre de archivo de la plantilla no funcionan como se espera si cambias el contexto (por ejemplo, si integras una plantilla CSS/JavaScripten un archivo HTML). En ese caso, establece

explcitamente el valor predefinido para la estrategia de escape automtico con la etiqueta autoescape.

Ver tambin
include

Filtros
date date_modify format replace number_format url_encode json_encode convert_encoding title capitalize nl2br upper lower striptags join split reverse abs length sort default

keys escape raw merge slice trim

date
Nuevo en la versin 1.1: La compatibilidad con la zona horaria se aadi en Twig1.1. Nuevo en la versin 1.5: La compatibilidad para el formato de fecha predefinido se aadi en Twig 1.5. Nuevo en la versin 1.6.1: El soporte para la zona horaria predeterminada se aadi en Twig 1.6.1 Nuevo en la versin 1.11.0: La introduccin del valor false para la zona horaria se introdujo en Twig 1.11.0 El filtro date es capaz de formatear una fecha con una forma suministrada explcitamente:
{{ post.published_at|date("m/d/Y") }}

El filtro date acepta cadenas (estas deben ser compatibles con los formatos de la funcin strtotime), instancias de DateTime o DateInterval. Por ejemplo, para mostrar la fecha actual, filtra la palabra "now":
{{ "now"|date("m/d/Y") }}

Para escapar palabras y caracteres en el formato de fecha usa \\ al frente de cada carcter:
{{ post.published_at|date("F jS \\a\\t g:ia") }}

Si el valor pasado al filtro date es null, por omisin devolver la fecha actual. Si en lugar de la fecha actual quieres una cadena vaca, utiliza un operador ternario:
{{ post.published_at is empty ? "" : post.published_at|date("m/d/Y") }}

Si no proporcionas un formato, Twig utilizar el formato predefinido: F j, Y H:i. Puedes cambiar fcilmente el predefinido llamando al mtodo setDateFormat() en la instancia de la extensin core. El primer argumento es el formato predefinido para fechas y el segundo es el formato predeterminado para los intervalos de fecha:
$twig = new Twig_Environment($loader); $twig->getExtension('core')->setDateFormat('d/m/Y', '%d days');

Zona horaria
De manera predefinida, la fecha se muestra aplicando la zona horaria predefinida (la especificada en php.ini o declarada en Twig ve ms adelante), pero la puedes sustituir explcitamente especificando una zona horaria (timezone):
{{ post.published_at|date("m/d/Y", "Europe/Paris") }}

Si la fecha ya es un objeto DateTime, y si quieres mantener la zona horaria actual, pasa false como el valor de la zona horaria:
{{ post.published_at|date("m/d/Y", false) }}

Puedes fijar globalmente la zona horaria predefinida llamando a setTimezone():

$twig = new Twig_Environment($loader); $twig->getExtension('core')->setTimezone('Europe/Paris');

Argumentos
format: El formato de fecha

timezone: La zona horaria para fechas

date_modify
Nuevo en la versin 1.9.0: El filtro date_modify se aadi en Twig 1.9.0. El filtro date_modify modifica una fecha con una cadena de caracteres modificadores suministrada:
{{ post.published_at|date_modify("+1 day")|date("m/d/Y") }}

El filtro date_modify acepta cadenas (deben estar en un formato compatible con la funcin strtotime) o ser instancias de DateTime. Fcilmente lo puedes combinar con el filtro date para aplicar formato.

Argumentos
modifier: El modificador

format
El filtro format filtra formatos de una cadena dada sustituyendo los marcadores de posicin (los marcadores de posicin siguen la notacin de printf):
{{ "Me gustan %s y %s."|format(foo, "bar") }}

{# devuelve Me gustan foo y bar si el parmetro foo es igual a la cadena foo. #}

Ver tambin
replace

replace
El filtro reemplaza formatos de una cadena dada sustituyendo los marcadores de posicin (los marcadores de posicin son libres):

{{ "Me gustan %this% y %that%."|replace({'%this%': foo, '%that%': "bar"}) }}

{# devuelve Me gustan foo y bar si el parmetro foo es igual a la cadena foo. #}

Argumentos
replace_pairs: Los valores de los marcadores de posicin

number_format
Nuevo en la versin 1.5: El filtro number_format se aadi en Twig 1.5 El filtro number_format formatea nmeros. Este es una envoltura en torno a la funcinnumber_format de PHP:
{{ 200.35|number_format }}

Puedes controlar el nmero de decimales, punto decimal, y separador de miles utilizando los argumentos adicionales:
{{ 9800.333|number_format(2, '.', ',') }}

Si no proporcionas opciones de formato entonces Twig usar las opciones de formato predefinidas:

0 lugares decimales.
. como el punto decimal. , como el separador de miles.

Estas opciones predefinidas se pueden cambiar fcilmente a travs de la extensin del ncleo:
$twig = new Twig_Environment($loader);

$twig->getExtension('core')->setNumberFormat(3, '.', ',');

Puedes ajustar las opciones predefinidas para number_format en cada llamada usando los parmetros adicionales.

Argumentos
decimal

: El nmero de puntos decimales a most

url_encode
El filtro url_encode produce una cadena URL codificada.
{{ data|url_encode() }}

Nota
Internamente, Twig utiliza la funcin urlencode de PHP.

rar
decimal_point: El carcter a utilizar para el punto decimal decimal_sep: El carcter a utilizar para el separador de miles

convert_encoding
Nuevo en la versin 1.4: El filtro convert_encoding se aadi en Twig 1.4. El filtro convert_encoding convierte una cadena de una codificacin a otra. El primer argumento es el juego de caracteres de salida esperado y el segundo es el juego de caracteres de entrada:
{{ data|convert_encoding('UTF-8', 'iso-2022-jp') }}

Nota
Este filtro est basado en la extensin iconv o mbstring, por lo tanto tienes que instalar una de ellas. En caso de que ambas estn instaladas, de manera

predeterminada se utiliza mbstring (Twig antes de 1.8.1 usaba iconv por omisin).

Argumentos
from: En juego de caracteres entrante to: El juego de caracteres saliente

title
El filtro title devuelve una versin con maysculas iniciales del valor. Es decir, las palabras deben empezar con letras maysculas, todos los caracteres restantes son minsculas:
{{ 'mi primer automvil'|title }}

{# produce 'Mi Primer Automvil' #}

capitalize
El filtro capitalize capitaliza un valor. El primer carcter ser en mayscula, todos los dems en minsculas:
{{ 'my first car'|capitalize }}

{# produce 'My first car' #}

nl2br
Nuevo en la versin 1.5: El filtro nl2br se aadi en Twig 1.5. El filtro nl2br inserta saltos de lnea HTML antes de todas las nuevas lneas en una cadena:

{{ "I like Twig.\nYou will like it too."|nl2br }} {# produce

I like Twig.<br /> You will like it too.

#}

Nota
El filtro nl2br primero escapa la entrada antes de aplicar la transformacin.

upper
El filtro upper convierte un valor a maysculas:
{{ 'bienvenido'|upper }}

{# produce 'BIENVENIDO' #}

lower
El filtro lower convierte un valor a minsculas:
{{ 'BIENVENIDO'|lower }}

{# produce 'bienvenido' #}

join

El filtro join devuelve una cadena que es la concatenacin de las cadenas de una secuencia:
{{ [1, 2, 3]|join }} {# devuelve 123 #}

El separador predeterminado entre los elementos es una cadena vaca, lo puedes definir con el primer parmetro opcional:
{{ [1, 2, 3]|join('|') }} {# devuelve 1|2|3 #}

Argumentos
glue: El separador

join
El filtro join devuelve una cadena que es la concatenacin de las cadenas de una secuencia:
{{ [1, 2, 3]|join }} {# devuelve 123 #}

El separador predeterminado entre los elementos es una cadena vaca, lo puedes definir con el primer parmetro opcional:
{{ [1, 2, 3]|join('|') }} {# devuelve 1|2|3 #}

Argumentos
glue: El separador

reverse

Nuevo en la versin 1.6: La compatibilidad para cadenas se aadi en Twig 1.6. El filtro reverse invierte una secuencia, un arreglo asociativo, o una cadena:
{% for use in users|reverse %} ... {% endfor %}

{{ '1234'|reverse }}

{# outputs 4321 #}

Nota
Adems trabaja con objetos que implementan la interfaz Traversable.

abs
El filtro abs devuelve el valor absoluto.
{# numero = -5 #}

{{ numero|abs }}

{# produce 5 #}

Nota
Internamente, Twig usa la funcin abs de PHP.

length
El filtro length devuelve el nmero de elementos de una secuencia o asignacin, o la longitud de una cadena:

{% if users|length > 10 %} ... {% endif %}

sort
El filtro sort ordena un arreglo:
{% for use in users|sort %} ... {% endfor %}

Nota
Internamente, Twig utiliza la funcin asort de PHP para mantener asociado el ndice.

keys
El filtro keys devuelve las claves de un arreglo. Es til cuando deseas iterar sobre las claves de un arreglo:
{% for key in array|keys %} ... {% endfor %}

escape
Nuevo en la versin 1.9.0: Las estrategias css, url y html_attr se aadieron en Twig1.9.0. El filtro escape escapa una cadena para una insercin segura en la salida final. Es compatible con diferentes estrategias de escape en funcin del contexto de la plantilla.

De manera predeterminada, se utiliza la estrategia de escape HTML:

{{ user.username|escape }}

Por conveniencia, el filtro e est definido como un alias:

{{ user.username|e }}

Adems, puedes usar el filtro escape fuera del contexto HTML gracias al argumento opcional que define la estrategia de escape a usar:
{{ user.username|e }} {# es equivalente a #} {{ user.username|e('html') }}

Y aqu tienes cmo escapar variables incluidas en cdigo JavaScript:

{{ user.username|escape('js') }} {{ user.username|e('js') }}

El filtro escape admite las siguientes estrategias de escape:

html: Escapa una cadena para el contexto HTML body. js: Escapa una cadena para el contexto JavaScript. css: Escapa una cadena para el contexto CSS. El escape CSS se puede aplicar a

cualquier cadena insertada en CSS y escapa todo excepto caracteres alfanumricos.

url: Escapa una cadena para los contextos URI o parameter. Este no se debe

usar para escapar una URI completa; slo un subcomponente insertado.

html_attr: Escapa una cadena para el contexto atributo HTML.

Nota
Internamente, escape utiliza la funcin htmlspecialchars nativa de PHP.

Prudencia

Al utilizar el escape automtico, Twig intenta no escapar doblemente una variable cundo la estrategia de escape automtico es la misma que la aplicada por el filtroescape; Pero esto no trabaja cundo utilizas una variable como estrategia de escape:
{% set strategy = 'html' %}

{% autoescape 'html' %} {{ var|escape('html') }} {# no se escapar doblemente #} {{ var|escape(strategy) }} {# no se escapar doblemente #} {% endautoescape %}

Cundo utilizas una variable como estrategia de escape, deberas desactivar el escape automtico:
{% set strategy = 'html' %}

{% autoescape 'html' %} {{ var|escape(strategy)|raw }} {# no se escapar doblemente #} {% endautoescape %}

Argumentos
strategy: La estrategia de escape charset: La cadena del juego de caracteres

raw
El filtro raw marca el valor como seguro, lo cual significa que en un entorno con escape automtico activado esta variable no ser escapada siempre y cuando raw sea el ltimo filtro que se le aplique:
{% autoescape true %}

{{ var|raw }} {# var won't be escaped #} {% endautoescape %}

slice
Nuevo en la versin 1.6: El filtro slice se aadi en Twig 1.6. El filtro slice extrae un segmento de una secuencia, un arreglo asociativo, o una cadena:
{% for i in [1, 2, 3, 4]|slice(1, 2) %} {# iterar en 2 y 3 #} {% endfor %}

{{ '1234'|slice(1, 2) }}

{# produce 23 #}

Puedes usar cualquier expresin vlida tanto para start como para length:
{% for i in [1, 2, 3, 4]|slice(start, length) %} {# ... #} {% endfor %}

Como azcar sintctica, tambin puedes utilizar la notacin []:

{% for i in [1, 2, 3, 4][start:length] %} {# ... #} {% endfor %}

{{ '1234'[1:2] }}

{# puedes omitir el primer argumento -- que es lo mismo que 0 #} {{ '1234'[:2] }} {# mostrar "12" #}

{# Puedes omitir el ltimo argumento -- con lo cul seleccionar todo hasta el final #} {{ '1234'[:2] }} {# mostrar "34" #}

El filtro slice trabaja como la funcin array_slice de PHP para los arreglos y substrpara las cadenas. Si start no es negativo, la secuencia iniciar en start en la variable. Si start es negativo, la secuencia comenzar en esa posicin desde el final de la variable. Si se especifica length y es positivo, entonces la secuencia tendr hasta tantos elementos en ella. Si la variable es ms corta que la longitud, entonces, slo los elementos disponibles en la variable estarn presentes. Si se especifica length y es negativo, entonces la secuencia se detendr hasta tantos elementos a partir del final de la variable. Si se omite, la secuencia tendr todo desde el desplazamiento hasta el final de la variable.

Nota
Adems trabaja con objetos que implementan la interfaz Traversable.

Argumentos
start: El inicio del segmento length: El tamao del segmento preserve_keys: Si preservar la clave o no (cundo la entrada es un arreglo)

trim
Nuevo en la versin 1.6.2: El filtro trim se aadi en Twig 1.6.2. El filtro trim quita los espacios en blanco (u otros caracteres) del principio y final de una cadena:

{{ ' Me gusta Twig. '|trim }}

{# produce 'Me gusta Twig.' #}

{{ ' Me gusta Twig.'|trim('.') }}

{# produce ' Me gusta Twig' #}

Nota
Internamente, Twig usa la funcin trim de PHP.

Argumentos
character_mask: Los caracteres a eliminar