Debugging compiled Twig templates

How Twig in Drupal normally works

By default, the Twig theming engine compiles templates into PHP code and stores the compiled template code in the filesystem (by default these files will be in sites/default/files/php/twig).

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 often caches it in such a way that Twig isn't involved at all in later page requests (if the cache metadata remains the same), so you may think Twig's debug or auto_reload settings aren't working, when in fact the render cache needs to be refreshed (or disabled if you prefer).

Caches can be cleared through Drupal's clear cache interface, but for ongoing development it's easier to change Drupal's settings so that the Render API does not cache anything at all. Be sure to test with the render cache on as well, otherwise it's easy to miss cache-related bugs that will occur on environments with caching enabled.

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

First enable Twig debugging as described in Debugging Twig templates

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/development.services.yml';
$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