Debugging Twig templates

Twig debug mode

The Twig template engine offers a debug mode. It sets Twig templates to be automatically recompiled whenever the source code changes, and allows the dump() function to be used in Twig templates to output information about template variables. The Drupal implementation also adds an additional tool that allows you to locate the template that outputs the markup.

Warning: Turning on Twig debug can break some parts of the site, especially Views. See this issue. It will also will cause automated tests that directly check rendered HTML to fail. It should not be enabled on production!

Enable Twig debug mode

From Drupal 10.1, Twig debugging can be enabled via Admin > Configure > Development settings (/admin/config/development/settings).

You can also enable Twig debug mode in a services file, by ensuring the debug variable is set to true like so:

parameters:
  twig.config:
    debug: true 

For local development, this should be configured in the development.services.yml file, which is referenced by your settings.local.php file (the link has instructions for setting up settings.local.php). Twig debug mode can also be configured in your primary services.yml file, but this can result in inadvertently enabling it on production and should be avoided.

To verify that Drupal is getting the twig.config parameter set as expected, run:

drush php:eval "var_export(\Drupal::getContainer()->getParameter('twig.config'));"

And check that the printed PHP array shows debug set as TRUE. If other twig.config sub-options are set, they should show as well. If twig.config is not correctly set, then check that the development.services.yml is correctly referenced in the settings.local.php file.

Other ways to enable Twig debug mode

You can also use the following options to enable Twig debugging:

1. Use Twig Debugger module to enable twig debugging.
2. Use Mix module to enable twig debug/auto_reload and disable caches for development.
3. Enable Twig Debugging with Drupal Console

Automatic reloading

Twig templates are compiled to PHP classes on disk for better performance, but this means by default your templates are not refreshed when you make changes. Don't enable this in production.

To manually rebuild the templates run drush cr. If you want to enable automatic reloading on its own when Twig debug mode is disabled, you can do so by setting twig.config.auto_reload: true in development.services.yml.

parameters:
  twig.config:
    auto_reload: true

Clear the cache after setting this parameter to ensure changes are applied.

For more information, see Debugging compiled Twig templates.

Use dump() to view variables

You can use Twig's dump() function to view variables, particularly if you are unable to set up Xdebug.

{{ dump() }}

{{ dump(variable_name) }}

List available variables (at top level):

{{ dump(_context|keys) }}

If you have Devel module, you can get an accordion display of the variables available to twig with:

{{ devel_dump() }}

Or you can use Twig vardumper module that contains vardumper for twig. You can get an accordion display of the variables available to twig with:

{{ dump() }}
{{ dump(variable_name) }}

{{ vardumper() }}
{{ vardumper(variable_name) }}

• https://www.drupal.org/project/twig_vardumper

... but also consider that spending an hour or two getting Xdebug working will make your life a lot easier as it takes all the guess work out of knowing which variables you can use.

Use Xdebug to view variables

Far and beyond the best way to deal with viewing variables is to use Xdebug.

If you use the other non-Xdebug methods noted below you will have many recursive things rendering which may result in pages and pages of information that are not useful to you.

The most often recommended approach is to use PHPstorm and Xdebug as the configuration is the most simple to get setup, however, almost all IDEs have a plugin for Xdebug. If you want a free editor that is fairly lightweight, Microsoft's VSCode editor is an open-source option that has plugins for PHP and Xdebug.

Setting up Xdebug

Setting up Xdebug can be complicated, so remember to read the instructions of your IDE's plugin, and review Xdebug's documentation for how to connect it. Simply reading howtos and bug reports online will be wasteful if you are targeting the wrong type of environment (ie, if your Xdebug is inside Vagrant, Virtualbox or Docker, you may need the "remote" connection instructions: https://xdebug.org/docs/remote).

Drupal.org provides Xdebug guides for various editors are available here: https://www.drupal.org/docs/develop/development-tools/xdebug-debugger

When you get Xdebug working:

There are three ways to set breakpoints in your Twig templates in order to have your IDE displaying the variables and other stateful information about the PHP environment:

• Use PHPStorm's new Twig debugging feature (blog, docs). No Drupal modules are needed.
• with module Devel
  

  {{ devel_breakpoint() }}

• with module Twig Xdebug
  

  {{ breakpoint() }}

If you are using the wrong paradigm...

One thing to consider if you are doing a lot of coding in twig is to ask yourself if you really need to be doing complex activities on this level. For example: consider if you are better off doing something like copying an existing field formatter plugin file into a custom module (remembering to use the same path structure) and simply changing the annotation (introduction comment, aka plugin name) and customizing the PHP/HTML to do what you want there. Plugins in Drupal 8 are just standalone files that live in specific folders and can be very easy to work with.

More debugging options can be found in the next section.