Depuración de plantillas Twig compiladas

Cómo funciona Twig normalmente

Por defecto, el motor de temas Twig compila las plantillas en código PHP y guarda el código compilado en memoria. El código compilado no es adecuado para desarrollo, ya que los cambios en las plantillas Twig no se actualizan inmediatamente en tu sitio Drupal.

Después de que Twig termina con cierto marcado, el Render API añade otro nivel de caché. Esto toma el marcado generado por Twig y lo cachea de tal forma que Twig no participa en las solicitudes posteriores de página, por lo que las opciones de depuración de Twig se ignoran finalmente.

Los cachés se pueden limpiar mediante la interfaz de limpieza de caché en Drupal, pero para el desarrollo es más fácil configurar Drupal para que ni Twig ni Render API cacheen nada.

Configuración de Twig y Render API para depuración

Los dos niveles, el API de Twig y el de Render, deben configurarse por separado para propósitos de depuración:

1. El motor Twig ofrece opciones para configurar la depuración, recarga automática (recompilación) de plantillas y caché de plantillas compiladas en el sistema de archivos. Esto se puede configurar en el services.yml de tu sitio.
2. La caché del API de renderizado se puede configurar en el archivo settings.php de tu sitio.

Detallaremos estos dos pasos a continuación.

1. Configurar Twig para depuración

Puedes usar Drupal Console para esto; o hacerlo manualmente.

Cómo habilitar la depuración con Drupal Console

Primero instala Drupal Console. Luego ejecuta:

drupal site:mode dev 

Nota que esto cambia muchas configuraciones, pero incluye cambiar los siguientes valores en tu sites/default/services.yml:

twig.config: { debug: true } 

Deberías ver algo parecido a esto:

Cómo habilitar la depuración manualmente

1. Encuentra el archivo services.yml de tu sitio, probablemente en sites/default/services.yml
2. Si services.yml no existe aún, copia default.services.yml y renómbralo a services.yml.
3. Edita el archivo services.yml y habilita una o varias opciones de depuración listadas abajo:
           - Opciones de depuración Twig
           - Twig con recarga automática
           - Caché Twig
4. Limpia la caché.

Localiza la sección twig.config en tu services.yml y modifica como en este ejemplo:

parameters:
  twig.config:
    debug: true 

Opciones de depuración de Twig

Nota: ¡no las actives en producción! Estas tres opciones deberían dejarse sin establecer (es decir, por defecto) en ambientes de producción.

- debug (por defecto: false)

Cuando debug: true está activado:

• El marcado de cada plantilla Twig se rodea con comentarios HTML que incluyen información sobre el tema, como sugerencias de nombres de archivo.
• Esta marcación de depuración hará que fallen las pruebas automatizadas que revisan directamente el HTML renderizado. Para pruebas automatizadas, twig_debug debe estar en FALSE.
• La función dump() puede usarse en plantillas Twig para mostrar información sobre variables.
• Las plantillas Twig se recompilan automáticamente al cambiar el código fuente (ver auto_reload abajo).

- auto_reload (por defecto: null, definido por debug arriba)

Cuando auto_reload: true está activado:

• Recompila automáticamente las plantillas Twig cada vez que cambia el código fuente. Si no especificas un valor para twig_auto_reload, este se define según twig_debug.
• Si no quieres auto_reload y no estás en modo depuración, no necesitas tocar esta opción. Simplemente activa debug.

- cache (por defecto: true, pero sobrescrito por debug arriba)

Cuando cache: false está activado:

• No desactives la caché Twig a menos que tengas una razón específica. Cuando activas debug (o solo auto_reload si no quieres debug), la caché Twig no te estorbará. Desactivar la caché ralentizará el desarrollo porque cada plantilla debe compilarse siempre, editada o no. Además, no podrás ver ni depurar fácilmente las plantillas Twig compiladas (clases PHP, por defecto en sites/default/files/php/twig) si no se cachean en disco.
• Por defecto, las plantillas Twig se compilan y guardan en el sistema de archivos para mejorar rendimiento. Desactivar la caché hará que se recompilen en cada uso. Generalmente, es mejor activar auto_reload y no desactivar la caché Twig.

2. Configurar la caché de Render API para depuración

Por defecto, Drupal cachea el renderizado de bloques y entidades para acelerar las cargas posteriores de página. Esto significa que los cambios en plantillas Twig para ellos no se reflejan inmediatamente. Configurar la caché de renderizado para usar caché nula efectivamente desactiva esto.

Para desactivar la caché de renderizado, añade las siguientes líneas:

• en settings.php, evitando agregarlo a tu sitio de producción
• o en settings.local.php, descomentando primero las líneas al final de tu settings.php.

Estas líneas:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null'; 

Es posible que ya estén en tu settings.php comentadas; si es así, simplemente descoméntalas (¡pero recuerda comentarlas luego!).

¡Lo lograste!

Con las configuraciones de Twig y Render API listas, limpia todas las cachés: puedes usar Drush o ir a Configuración -> Rendimiento y hacer clic en "Limpiar todas las cachés".

Finalmente, recarga la página que estás revisando: deberías ver información de depuración Twig en el código fuente, y las actualizaciones de las plantillas Twig deberían aplicarse inmediatamente a cualquier página actualizada.