Debugging compiled Twig templates

Last updated on
5 January 2018

How Twig normally works

By default, the Twig theming engine compiles templates into PHP code and stores the compiled code in memory. Compiled code is unsuitable for development, since changes in Twig templates are not immediately updated in your Drupal site.

After Twig is finished with some markup, there's another layer of caching in the Render API. This takes the markup created by Twig, and caches it in such a way that Twig isn't involved at all in later page requests, so Twig's debug settings end up ignored.

Caches can be cleared through Drupal's clear cache interface, but for ongoing development it's easier to change Drupal's settings so that neither Twig nor the Render API cache anything at all.

Configuring Twig and Render API for debugging

The two layers of Twig and Render API must be configured separately, for debugging purposes:

  1. The Twig engine provides options for configuring debugging, automatic reloading (recompiling) of templates, and caching compiled templates in the filesystem. This can be configured in your site's services.yml.
  2. Render API's caching can be configured in your site's settings.php.

We go through these two stages in more depth below.

1. Configuring Twig for debugging

You can use Drupal Console to do this; or make the changes manually.

How to enable debugging with Drupal Console

First, install Drupal Console. Then run:

drupal site:mode dev 

Note that this changes a lot of settings, but includes a change to the following values in your sites/default/services.yml:

twig.config: { debug: true } 

You should see something similar to this:

How to enable debugging manually

  1. Locate your site's services.yml file, likely located in sites/default/services.yml
  2. If services.yml does not yet exist; copy and rename it to services.yml.
  3. Edit the services.yml file and enable one or more of the debugging options defined below:
    • Twig debugging options
    • Twig auto-reload
    • Twig cache
  4. Rebuild cache.

Locate the twig.config parameters in your services.yml and make changes there. Example:

    debug: true 

Twig debugging options

Note: do not set these on production! These three options should be left unset (i.e. as their defaults) on production environments.

debug (default: false)

When debug: true is set:

  • The markup of each Twig template is surrounded by HTML comments that contain theming information, such as template file name suggestions.
  • Note that this debugging markup will cause automated tests that directly check rendered HTML to fail. When running automated tests, 'twig_debug' should be set to FALSE.
  • The dump() function can be used in Twig templates to output information about template variables.
  • Twig templates are automatically recompiled whenever the source code changes (see auto_reload below).

auto_reload (default: null, determined by debug above)

When auto_reload: true is set

  • Automatically recompile Twig templates whenever the source code changes. If you don't provide a value for twig_auto_reload, it will be determined based on the value of twig_debug.
  • Unless you specifically want auto_reload and NOT debug, you don't need to touch this setting. Just enable debug above.

cache (default: true, but overridden by debug above)

When cache: false is set:

  • Unless you have a specific use case, do not disable the Twig cache. When you enable Twig debug (or just auto_reload if for some reason you don't want to enable debug) the Twig cache won't get in your way. Disabling the Twig cache will only make for a slower development experience because each template would need to be compiled regardless of whether it's been edited or not. Also, you can't easily look at or debug the compiled Twig templates (PHP classes, by default in sites/default/files/php/twig) if they are not cached to disk.
  • By default, Twig templates will be compiled and stored in the filesystem to increase performance. Disabling the Twig cache will recompile the templates from source each time they are used. In most cases the twig_auto_reload setting above should be enabled rather than disabling the Twig cache.

2. Configuring Render API cache for debugging

By default, Drupal caches any rendering it performs for blocks and entities, to speed up subsequent page loads. This means that changes to Twig templates for these will not take effect immediately. Setting the render cache to use the Null cache back-end effectively disables this.

To disable the render cache, add the following lines to either:

  • settings.php, taking care not to add it to your production site
  • or settings.local.php, by uncommenting the lines at the bottom of your settings.php first.

These lines are:

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

You might find that they are already in your settings.php, commented out; if so, just uncomment them (but remember to comment them out again later!)

You're done!

With both the Twig and Render API settings in place, clear all caches: you can use Drush, or go to Configuration -> Performance and then click the Clear all caches button.

Finally, refresh the page you are inspecting: you should see Twig debugging information in the page source, and updates to Twig templates should propagate immediately to any refreshed page.

Further reading

For more information about the implementation of the Twig environment settings in Drupal, visit #1843034: Make Twig settings configurable