How I Stepped My Way Through a Failing Drush Drupal 8 Migration With PHPStorm’s Xdebug Integration...PART 1 of 2

August 3, 2017
blog author


Senior Developer

I was recently going through the d8cards set of exercises to test my knowledge of Drupal 8 APIs, as one does in the dev world...

Put simply, or as simply as possible, it consists of a set of 21 exercises, each going over a common Drupal task and how it changes from Drupal 7 to Drupal 8. Card number 4, covering the migration API now semi-bundled with core, gave me enough of a hard time that I had to upgrade my entire development environment to solve it. 

Here is a story of how I debugged a Drupal 8 migration entity, first by setting up a CLI Xdebug environment, then by applying debug thinking to hunt down the cause of a bug that was actually a feature. Follow along by opening the Migration 101 d8card. You may wish to attempt the exercise yourself before continuing.

The Bug

Being a stereotypical overoptimistic coder, I assumed I would breeze through the migration by “borrowing” some example code and adjusting a few variables here and there. Everything worked fine for the actors migration, but when attempting the movies, this was the outcome:


Looks like an obvious problem — the code is attempting to insert the raw value from the source into the destination, without converting it into a taxonomy term id. But, being unfamiliar with Drupal 8 migrations, where can we begin to look for the cause?

The old way of debugging this problem would involve wrapping the different steps of the migration in var_dump calls and other such print statements, crudely observing the data flow. In Drupal 8, however, migrations are configuration entities written in YML files, therefore can’t be debugged the old-fashioned PHP way. No need to worry, we have something much better: Xdebug and live, interactive debugging, in the best IDE for such hard work, PHPStorm.

Our immediate challenge: the migrate API for Drupal 8 does not have a web interface for migrations yet. Migrations are meant to be processed through the CLI, using Drush or Drupal console. This means the old trick of passing Xdebug remote connection parameters to web pages is useless; we will need to trigger debugging on a terminal script.

For our development environments, we favor using the Drupal-VMprovisioning script. It’s fast to set up, it’s easily shared using one configuration file, and it runs on plain old reliable Vagrant.

It’s also easy to combine with the Drupal-Project composer scaffold, which conveniently installs both Drush and Drupal console into the project’s vendor directory. This means we have the Drush code as part of the same project as the rest of our code, creating the ideal debugging setup.

Before we can start our debugging session we have to do some necessary setup. PHPStorm is able to run scripts inside a Vagrant VM, but we first need to tell it about our “remote interpreter”.

Configuring a Vagrant Remote Interpreter

Open the PHPStorm Preferences, and under “Language & Frameworks > PHP”, you should see this screen:

We’re going to configure a new CLI interpreter by selecting “…” next to the CLI Interpreter dropdown. This opens the CLI interpreters dialog:

Create a new Remote interpreter by selecting “+” in the top left and choosing “From Docker, Vagrant, VM, Remote…” in the dropdown.

The configuration details should reflect the configuration options of our Drupal VM virtual machine. The username and password is typically vagrant/vagrant. Click ‘OK’ to continue.

Now we need to map the files in our project, located on our host machine, to the files that are being synced to the VM. Next to “Path mappings:” click “…” and select the local and remote paths that you linked in Drupal VM’s config.yml file.

The final step is verifying that our debugging configuration is still correct. Open the “PHP” toggle and select “Debug”:

Check ‘Break at first line in PHP scripts’. We’ll use it to validate our configuration worked.

Close the PHPStorm Preferences....

Now, I know you want to know more, so tune in next week for Stepping Through Drush....and later, The Art and Science of Debugging....