Debugging Twig templates
This documentation needs work. See "Help improve this page" in the sidebar.
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; copydefault.services.yml
toservices.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 thesites/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:
- Use Twig Debugger module to enable twig debugging.
- Use Mix module to enable twig debug/auto_reload and disable caches for development.
- 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) }}
... 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.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion