Debugging Twig templates

Last updated on
9 February 2017

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.

Enable debugging

You enable Twig Debugging in sites/default/services.yml.
(If services.yml does not yet exist; copy default.services.yml and copy it to services.yml.)

Set the debug variable to true.

parameters:
  twig.config:
    debug: true 

If you are using Firebug (in Firefox) make sure that "Show Comments" is enabled or view page source directly:

Firebug setting for twig debug

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.

Printing variables

Far and beyond the best way to deal with printing out 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 farily 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 waseful 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:

Install the following module and follow the instructions on the module page to put {{ breakpoint() }} and other fun stuff in your twig code. It will output the variables and other stateful information about the PHP environment.

If you cannot get xdebug setup...

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

{{ dump() }}
{{ dump(var) }}

If you have Devel's kint submodule (install to require-dev with Composer using composer require --dev drupal/devel 1.0-alpha1 and install with Drush with drush -y en kint) you can get an accordion display of the variables available to twig with:

{{ kint() }}

There is a very good chance that kint will lock up your browser when the rendering gets very big. In that case the following modules may work better for you:

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