Debugging Compiled Twig Templates

How Twig Normally Works

By default, the Twig theming engine compiles templates into PHP code and stores the compiled code in memory. This compiled code is not ideal for development because changes to Twig templates do not immediately reflect on your Drupal site.

Once Twig finishes rendering markup, the Render API adds another layer of caching. It stores the markup created by Twig in such a way that Twig is not involved in subsequent page requests, effectively ignoring Twig debugging settings.

You can clear caches via the cache-clear interface in Drupal, but for ongoing development it's easier to configure Drupal so that neither Twig nor the Render API cache anything at all.

Configuring Twig and Render API for Debugging

There are two layers to configure for debugging purposes:

1. Twig engine provides options for debugging, automatic template reload, and compiled template caching to the filesystem. This is configured in your site's services.yml file.
2. Render API caching is configured in your site's settings.php file.

We’ll walk through both in more detail below.

1. Configuring Twig for Debugging

You can use the Drupal Console or make manual changes.

Enable Debugging with Drupal Console

First, install Drupal Console. Then run:

drupal site:mode dev

Note this changes many settings, but includes updating the following in sites/default/services.yml:

twig.config: { debug: true }

You should see output like this:

Enable Debugging Manually

1. Locate your site's services.yml file, likely at sites/default/services.yml
2. If services.yml doesn’t exist, copy default.services.yml and rename it to services.yml.
3. Edit the file and include one or more of the debugging options below:
      - Twig debug options
      - Twig auto_reload
      - Twig cache
4. Rebuild the cache.

Find the twig.config section in services.yml and update it. Example:

parameters:
  twig.config:
    debug: true

Twig Debug Options

Note: Do not enable these on production! These three parameters should remain at default in production environments.

- debug (default: false)

When set to debug: true:

• Each Twig template's output is wrapped in HTML comments showing theme hooks, template file suggestions, and paths.
• This debug markup will break tests that check rendered HTML directly. Set twig_debug to FALSE for automated tests.
• The dump() function becomes available for inspecting template variables.
• Templates auto-recompile when changed (see auto_reload below).

- auto_reload (default: null, inherited from debug)

When set to auto_reload: true:

• Templates auto-recompile when the source file changes.
• If not explicitly set, auto_reload inherits the value of debug.

- cache (default: true, overridden by debug)

When set to cache: false:

• If not needed, don’t disable Twig cache. Enabling debug or auto_reload is often sufficient.
• Disabling cache slows development, as all templates are recompiled every time.
• You can’t inspect compiled PHP templates if cache is disabled (they live in sites/default/files/php/twig).

2. Configuring Render API Cache for Debugging

By default, Drupal caches block and entity rendering for faster page loads. This means Twig template changes won’t reflect immediately. You can disable render caching by using a null cache backend.

To disable render caching, add the following to:

• settings.php (not recommended for production), or
• settings.local.php (enable settings.local.php by uncommenting lines at the bottom of settings.php).

$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 may find these lines already present but commented out in settings.php; if so, just uncomment them (but remember to re-comment them later for production).

You Did It!

With both Twig and Render API configured for debugging, clear all caches: use Drush or go to Configuration → Performance and click “Clear all caches.”

Finally, refresh the page you’re testing. You should now see Twig debug comments in the page source, and your template changes should reflect immediately.