Debugging Your Migrations in Drupal 8

Aug 19 2016

One of the most useful features of Drupal 8 is the migration framework in core, and there are already plenty of plugins to work with different sources that are available in contributed modules. When writing your own code, it must always be debugged. As migrations can only be started with Drush, the debugging can be a bit challenging. And it gets even more interesting when you develop your website in a Vagrant box. In this tutorial, we will go through setting up xDebug and PhpStorm to debug your migrations. At a glance, the setup consists of:

Adding a PHP interpreter (Vagrant or SSH) in PhpStorm;
Download drush.phar to docroot; and,
Setup PhpStorm configuration for debugging and path mapping.

Let’s explore each item in more detail.

Interpreter

Beginning with PhpStorm 8, this IDE has the ability to set up remote interpreters. Navigate to Default Preferences → Languages & Frameworks; then, you can add new interpreter under PHP.

When you set up an interpreter, you can choose between Vagrant, SFTP Deployment, and SSH Credentials. We have had the most success with SSH Credentials. Here is what the configuration screen of the Interpreter looks like:

IP address 192.168.56.132 is the address of our local Vagrant box. The credentials are usually vagrant / vagrant.

Drush

The next step is to set up Drush. You have probably installed Drush globally on your Vagrant box. What we need to do is to have Drush inside your docroot folder. It will be used as a script to debug in PhpStorm. To do that, download drush.phar from https://github.com/drush-ops/drush. First, go to Releases:

And then download the latest version of the drupal.phar file:

Place the file in your docroot folder, next to index.php.

PhpStorm Configuration

Now we are ready to configure PhpStorm for debugging. To do that, create a PHP Script Configuration and point it to the downloaded drush.phar file:

An important note is to click on the “Fix” button in the bottom-right corner to choose our configured interpreter and set up path mappings:

Now you should be good to go! Add a breakpoint in any file involved in migration and start debugging.

For this example, we are using the CIBox setup of Vagrant. ImageX has extensive experience in migrations to both Drupal 7 and 8. Connect with us below if we can help you with your next migration project.