Debugging Twig templates with Drupal VM + Xdebug + PHPStorm

April 9, 2019

Drupal VM comes preconfigured to support Xdebug but being super new at Twig debugging/Xdebug, it took quite a bit of research to get it to the point where I can debug Twig templates within PHPStorm. I tried to document my journey for others to check out, hopefully it helps!

Requirements:

  • Drupal 8.6.x site running in Drupal VM (I'm also using BLT)
  • PHPStorm 2018/2019
  • Devel module enabled

Configure the VM to use Xdebug

This bit of YAML is what is in my VM configuration file. I'm using this with Acquia's BLT but, it should work with regular Drupal VM configurations too.

# XDebug configuration.
php_xdebug_version: 2.6.1
# Change this value to 1 in order to enable xdebug by default.
php_xdebug_default_enable: 1
php_xdebug_coverage_enable: 0
php_xdebug_cli_disable: no
php_xdebug_remote_enable: 1
php_xdebug_remote_connect_back: 1
# Use PHPSTORM for PHPStorm, sublime.xdebug for Sublime Text.
php_xdebug_idekey: PHPSTORM
php_xdebug_max_nesting_level: 256
php_xdebug_remote_port: "9000"
php_memory_limit: "512M"

After changing your configuration, re-provision your VM by running vagrant provision.

Something that was specifically tripping me up was the php_xdebug_cli_disable setting. By default, mine was set to yes, which lead me to be unsuccessful in ever verifying that it was running, so make sure that is set to 'no' before running the next step.

Verify Xdebug is running

Confirm that xdebug is running on your VM by running vagrant ssh

Then once logged into the VM, run: php -i | grep xdebug

And this should produce an output similar to the following screenshot:

Disable Drupal caches

I followed the information in this Drupal.org community documentation page: Disable Drupal 8 caching during development. If you don't have a local.settings.php file or something similar, there are instructions in the previous link on how to create one.

Since I'm using BLT, my needs were slightly different, so it was important to understand how BLT handles settings.php files. There is a hierarchy of files that is definitely good to know when changing your settings.

Verify the following is in local.settings.php or settings.local.php (whatever you're using). Keep in mind that these settings may already been defined in your settings files, so I wouldn't mindlessly paste this, use it as a reference of what should be enabled at a glance.

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;

$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

$settings['cache']['bins']['page'] = 'cache.backend.null';

$settings['extension_discovery_scan_tests'] = FALSE;

In sites/development.services.yml

services:
  cache.backend.null:
    class: Drupal\\Core\\Cache\\NullBackendFactory
# If using BLT, this can go in your sites/blt.development.services.yml
parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

Now clear those caches with drush cr

Configure PHPStorm

In PHPStorm go to Preferences > Language & Frameworks > PHP, then click the three dots ... next to "CLI Interpreter:"

Now click the + symbol and choose the option for "From Docker, Vagrant, VM, Remote..." In my case, PHPStorm figured out the rest and I was left with my CLI Interpreters screen looking like this:

Add the JavaScript bookmarklet

I used the bookmarklet that was suggested by the PHPStorm documentation. It's called Xdebug helper.

This extension will send debugging info to PHPStorm so there's a connection between your IDE and development site.

Turn on listening in PHPStorm

Go to Run > Start Listening for PHP Debug Connections.

Get debugging!

Lastly, go into whichever Twig template you want to debug and insert a {{ devel_breakpoint() }} to trigger a breakpoint in PHPStorm.

Example of using {{ devel_breakpoint() }} within a Drupal 8 template file. Additionally, this works with component based theming approaches.

In the Debugger panel in PHPStorm, locate the "Variables" pane to inspect what variables are available to you.

Helpful resources

To put this post together, I gathered information from a bunch of sources. Here they are in case you'd like to dive even deeper.