Depuración de plantillas Twig

El motor de plantillas Twig ofrece una herramienta de depuración.

La implementación de Drupal 8 también añade una herramienta adicional que te permite encontrar la plantilla que genera el marcado.

Advertencia: habilitar la depuración de Twig puede romper algunas partes del sitio, especialmente Views. Consulta este problema.

Habilitar la depuración

Habilitas la depuración Twig en sites/default/services.yml.

Establece la variable de depuración en true. Luego limpia la caché.

parameters:
  twig.config:
    debug: true 

• Si services.yml no existe aún; copia default.services.yml a services.yml.
• Si Drupal ya está instalado, quizás necesites cambiar temporalmente los permisos del directorio sites/default para permitir escritura.
• Cómo cambiar permisos de directorio
• Una vez creado y editado services.yml, cambia los permisos nuevamente para bloquear el directorio sites/default.

Verificar la depuración

Si usas Firebug (en Firefox), asegúrate de que la opción “Mostrar comentarios” ("Show Comments") esté activada, o revisa directamente el código fuente de la página:

Recarga automática

Las plantillas Twig se compilan en clases PHP en disco para mejorar el rendimiento, pero esto significa que por defecto tus plantillas no se actualizan al hacer cambios. No habilites esto en producción.

Para reconstruir manualmente las plantillas, ejecuta drush cr. Para ahorrar tiempo durante el desarrollo, habilita la recarga automática configurando twig.config.auto_reload: true en services.yml (por defecto la recarga automática se activa si twig.config.debug: true).

Para más información, consulta https://drupal.org/node/1903374.

Visualización de variables

La mejor forma de manejar la visualización de variables es usando Xdebug.

Si usas otros métodos sin Xdebug, que se indican a continuación, tendrás muchas operaciones recursivas de renderizado que pueden generar páginas y páginas de información que no te serán útiles.

El método más recomendado es usar PHPStorm y Xdebug, ya que la configuración es la más sencilla, aunque casi todas las IDEs tienen plugins para Xdebug. Si quieres un editor gratuito y ligero, el editor VSCode de Microsoft es una opción de código abierto con plugins para PHP y Xdebug.

Configuración de Xdebug

Configurar Xdebug puede ser complicado, así que asegúrate de leer las instrucciones del plugin de tu IDE y la documentación de Xdebug para conectarlo. Leer solo instrucciones y reportes de errores en línea no servirá si apuntas al tipo incorrecto de entorno (por ejemplo, si tu Xdebug está dentro de Vagrant, Virtualbox o Docker, podrías necesitar instrucciones de conexión “remota”: https://xdebug.org/docs/remote).

Drupal.org ofrece guías para Xdebug con varios editores aquí: https://www.drupal.org/docs/develop/development-tools/xdebug-debugger

Cuando trabajes con Xdebug:

Existen tres maneras de poner puntos de interrupción (breakpoints) en tus plantillas Twig para que tu IDE muestre variables y otra información del estado del entorno PHP:

• Usa la nueva función de depuración Twig en PHPStorm (blog, documentación). No se necesitan módulos Drupal.
• Con el módulo Devel:

{{ devel_breakpoint() }}

• Con el módulo Twig Xdebug:

{{ breakpoint() }}

Si no puedes instalar Xdebug ...

... sigue leyendo y buena suerte, amigo mío.

{{ dump() }}

{{ dump(variable_name) }}

Lista de variables disponibles (a nivel superior):

{{ dump(_context|keys) }}

Si tienes el submódulo Devel kint (requiere instalación vía composer con composer require --dev drupal/devel 1.0-alpha1 y habilitación con Drush mediante drush -y en kint), puedes obtener una visualización ordenada de las variables disponibles para la rama con:

{{ kint() }}

Existe una alta probabilidad de que kint bloquee tu navegador cuando el renderizado sea muy grande. En ese caso, estos módulos podrían funcionar mejor para ti:

• https://www.drupal.org/project/vardumper

O puedes usar el módulo Vardumper Twig, que contiene Vardumper para twig. Puedes obtener una visualización ordenada de las variables disponibles en twig:

{{ dump() }}
{{ dump(variable_name) }}

{{ vardumper() }}
{{ vardumper(variable_name) }}

• https://www.drupal.org/project/twig_vardumper

... pero también considera que invertir una o dos horas en hacer funcionar Xdebug hará tu vida mucho más fácil, porque te permitirá saber qué variables puedes usar.

Si estás usando un paradigma incorrecto ...

Si haces mucha programación en la plantilla, deberías preguntarte si realmente necesitas hacer acciones complejas a ese nivel. Por ejemplo: considera si sería mejor copiar un archivo de plugin de formateador de campos existente a un módulo personalizado (sin olvidar usar la misma estructura de ruta), y simplemente cambiar la anotación (comentario introductorio, también llamado nombre del plugin) y la configuración PHP/HTML para hacer lo que quieres allí. Los plugins en Drupal 8 son simplemente archivos separados que se encuentran en carpetas específicas y son muy fáciles de manejar.

Más opciones de depuración pueden encontrarse en la siguiente sección.