Debug dei template Twig compilati

Come funziona normalmente Twig

Per impostazione predefinita, il motore di templating Twig compila i template in codice PHP e salva il codice compilato in memoria. Il codice compilato non è adatto allo sviluppo, poiché le modifiche nei template Twig non vengono aggiornate immediatamente sul tuo sito Drupal.

Dopo che Twig ha terminato la generazione di un certo markup, entra in gioco un ulteriore livello di cache del Render API. Questo prende il markup creato da Twig e lo memorizza in cache in modo tale che Twig non venga affatto coinvolto nelle richieste successive delle pagine, motivo per cui le impostazioni di debug di Twig vengono alla fine ignorate.

Le cache possono essere svuotate tramite l’interfaccia di Drupal, ma per uno sviluppo più fluido è più semplice modificare le impostazioni di Drupal affinché né Twig né il Render API facciano caching.

Configurare Twig e Render API per il debug

I due livelli di API, Twig e Render, devono essere configurati separatamente a fini di debug:

1. Il motore Twig fornisce opzioni di configurazione per il debug, il ricaricamento automatico (ricompilazione) dei template e il caching dei template compilati nel filesystem. Questo può essere configurato in services.yml del tuo sito.
2. La cache del Render API può essere configurata nel file settings.php del tuo sito.

Vediamo in dettaglio entrambi i passaggi.

1. Configurazione di Twig per il debug

Puoi usare Drupal Console per questo; oppure modificare i file manualmente.

Come abilitare il debug con Drupal Console

Per prima cosa installa Drupal Console. Poi esegui:

drupal site:mode dev

Nota che questo comando modifica diverse impostazioni, tra cui i seguenti valori in sites/default/services.yml:

twig.config: { debug: true }

Dovresti vedere qualcosa di simile a questo:

Come abilitare il debug manualmente

1. Trova il file services.yml del tuo sito, di solito in sites/default/services.yml
2. Se services.yml non esiste ancora, copia default.services.yml e rinominalo in services.yml.
3. Modifica services.yml e abilita uno o più parametri di debug tra quelli sotto elencati:
    - Opzioni di debug Twig
    - Auto_reload di Twig
    - Cache di Twig
4. Ricostruisci la cache.

Cerca la sezione twig.config nel tuo services.yml e modificala. Ad esempio:

parameters:
  twig.config:
    debug: true

Opzioni di debug Twig

Nota: non abilitarle in produzione! Queste tre opzioni devono rimanere disattivate (valori di default) negli ambienti di produzione.

- debug (default: false)

Quando imposti debug: true:

• Il markup di ogni template Twig viene circondato da commenti HTML contenenti informazioni sui temi, ad esempio i suggerimenti per i nomi dei file dei template.
• Questi commenti di debug possono causare il fallimento di test automatici che verificano direttamente l’HTML renderizzato. Durante i test automatici, twig_debug deve essere impostato su FALSE.
• La funzione dump() può essere usata nei template Twig per stampare informazioni sulle variabili.
• I template Twig vengono ricompilati automaticamente quando cambia il codice sorgente (vedi auto_reload qui sotto).

- auto_reload (default: null, determinato dal debug)

Quando imposti auto_reload: true:

• I template Twig vengono ricompilati automaticamente a ogni modifica del sorgente. Se non fornisci un valore per twig_auto_reload, esso verrà dedotto da twig_debug.
• Se non vuoi auto_reload e non vuoi il debug, non toccare questo parametro. Ti basta attivare il debug.

- cache (default: true, ma sovrascritto dal debug)

Quando imposti cache: false:

• A meno di esigenze particolari, non disattivare la cache Twig. Abilitando il debug (o auto_reload), la cache Twig non interferirà. Disabilitare la cache Twig rallenta lo sviluppo, poiché ogni template deve essere ricompilato a ogni utilizzo. Inoltre, non puoi esaminare facilmente i template Twig compilati (classi PHP salvate in sites/default/files/php/twig) se non vengono scritti su disco.
• Per default i template Twig vengono compilati e salvati sul filesystem per migliorare le performance. Disabilitando la cache, i template vengono compilati dal sorgente ogni volta. Nella maggior parte dei casi è meglio usare auto_reload piuttosto che disabilitare completamente la cache.

2. Configurazione della cache del Render API per il debug

Per impostazione predefinita, Drupal mette in cache il rendering di blocchi ed entità per velocizzare il caricamento delle pagine. Questo significa che le modifiche ai template Twig non hanno effetto immediato. Configurando la cache del Render API come “null cache” la disattivi.

Per disabilitare la cache del rendering, aggiungi le seguenti righe:

• nel file settings.php (assicurati di non aggiungerle in produzione)
• oppure in settings.local.php, dopo aver decommentato le righe alla fine del tuo settings.php.

Le righe da inserire sono:

$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';

Potresti trovare queste righe già presenti in settings.php, commentate; in tal caso basta decommentarle (e ricordati di ricommentarle più tardi!).

Fatto!

Con le impostazioni di Twig e Render API configurate, svuota tutte le cache: puoi usare Drush o andare su Configurazione → Prestazioni e cliccare su “Svuota tutte le cache”.

Infine, ricarica la pagina che stai verificando: dovresti vedere le informazioni di debug Twig nel sorgente della pagina e gli aggiornamenti dei template Twig dovrebbero propagarsi immediatamente a ogni refresh.