Debugging Twig templates

Last updated on
16 February 2018

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

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

Set the debug variable to true. And clear cache.

    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

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 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: provides Xdebug guides for various editors are available here:

When you get Xdebug working:

There is two 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:

  • with module Devel
    {{ devel_breakpoint() }}
  • with module Twig Xdebug
    {{ breakpoint() }}

If you cannot get Xdebug setup... 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:

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) }}

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