Debugging Twig templates

The Twig template engine offers a debug tool.

The Drupal 8 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.

Enable debugging

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

This can also be controlled by enabling Twig Debugging in sites/default/services.yml or a services override such as development.services.yml.

Enabling Twig debugging via services.yml

Set the debug variable to true. And clear cache.

parameters:
  twig.config:
    debug: true 

• If services.yml does not yet exist; copy default.services.yml to services.yml.
• If Drupal has already been installed, permissions on the sites/default directory may need to be temporarily changed to allow write access.
• How to change directory permissions
• Once services.yml has been created and edited, change permissions back to lock down the sites/default directory.

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.

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. To save time during development, enable automatic reloading by setting twig.config.auto_reload: true in services.yml (by default, auto reloading will turned on with twig.config.debug: true).

For more information, see https://drupal.org/node/1903374.

Viewing 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 cannot get Xdebug setup...

...read on and good luck to you my friend.

{{ 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.

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.