Drupal 8: Debug Kernel, Functional and Unit Tests in PhpStorm by Xdebug

Submitted by Peter Majmesku on Sun, 04/16/2017 - 20:21

The following article is valid for unix based systems like Ubuntu Linux. It teaches you, how to setup your PhpStorm IDE to debug your unit tests via the Xdebug PHP extension in Drupal 8.

  1. Make sure you have read the article at https://www.drupal.org/docs/8/phpunit/running-phpunit-tests to understand how to run automated tests in Drupal 8.
  2. Make sure you have read the article at https://www.jetbrains.com/help/phpstorm/2017.1/configuring-xdebug.html to understand how to setup the Xdebug PHP extension on your system and configure it within PhpStorm.

phpunit.xml Configuration File

For the PhpStorm config you need to make sure to have the phpunit.xml file created by copying the ~/PhpstormProjects/drupal-8.x/core/phpunit.xml.dist into the same directory. Afterwards you must set the environment variables for 

    • Example value: mysql://user:password@localhost/d8-4.x
    • You can also use a SQLite database (faster). Mind the two slashes between the host and the filesystem location: sqlite://localhost//tmp/test.sqlite
    • Example value: ~/PhpstormProjects/drupal-8.4.x-dev/sites/simpletest/browser_output
    • Example value: serverName=d8-4x.dev
    • Be careful in this line! Here you set a key-value pair in the value field. Do not use any quotes here. The full line entry in my config is: <env name="PHP_IDE_CONFIG" value="serverName=d8-4x.dev"/>
    • Example value: idekey=PHPSTORM
    • Again: a key-value pair as value.

in your newly created phpunit.xml file.

PHPUnit Config in Your PhpStorm Project

Make sure you have configured:

  • path to the autoloader script from composer. It is located in ~/PhpstormProjects/drupal-8.4/vendor/autoload.php
  • path to your phpunit.xml file

The config window must look according to the following screenshot (be careful about the paths on your system):


PHPUnit config

Define the Server Setting and Map the Tests Directory

Set exactly the same value, which you have previously set in your phpunit.xml file inside the PHP_IDE_CONFIG environment variable for your server. You must also map the directory where your tests are. Do your settings according to the screenshot below.

Server setting directory mapping.

Uncheck the option  "Force break at first line when no path mapping specified" in PHPStorm

You might experience an error like "Cannot find file 'home/user/project/root/-' locally". Therefor you must uncheck the option "Force break at first line when no path mapping specified" at Settings/Languages & Frameworks/PHP/Debug in PHPStorm.


Path to CLI PHP Interpreter

Set the path to the PHP interpreter which is running your command line based scripts. It is usually located at /usr/bin/php. The config must look like in the following screenshots.

php interpreter
php cli

Run a Test File

For being able to execute your test quickly, open the PHP file with your test and hit the debug icon.

Run the test

Step into your PHP code

Happy debugging

XDebug: Debug PHP scripts which are executed by Drush within your virtual machine

Submitted by Peter Majmesku on Mon, 08/29/2016 - 20:39

If you have PhpStorm (2016.1.1) installed on your host system and you want to debug PHP code in your virtual machine, which is executed by Drush (PHP command line application), so you need some configuration which is described below.

Settings in your PhpStorm IDE:

Map your project root folder to the absolute path on the server. Make sure that your webapplication's PHP code (e.g. Drupal) is located in the same folder as Drush. Like in the screenshot below.

PhpStorm Xdebug

Uncheck "Force break at the first line when a script is outside the project":

PhpStorm Xdebug

PhpStorm needs to listen to XDebug connections:


Afterwards you are able to Debug the code within Drush itself. But it is not necessarily needed to have the Drush folder mapped, when you want to only debug your Drupal code.

Install Drush via composer (PHP package manager)

composer require "drush/drush:7.3"

I have choosen a specific Drush version to suit in my webapplication's requirements. Run this command in the folder, which contains also your webapplication, to meet the path mappings:

/project-folder (run the command here)

 Drush is then located at "vendor/drush/drush". Make sure to run the Drush file which is located there by creating an alias in your .bash_profile file:

alias drush='php /var/www/vendor/drush/drush/drush.php'

Configure your PHP CLI (command line) settings, to work with XDebug

xdebug.remote_autostart=true (THIS SETTING ENABLES/DISABLES XDEBUG)
xdebug.remote_host=YOUR HOST IP. - E.G: 

Force XDebug to break, so that you can set the path mapping

Use the following function in your code, to make XDebug connecting back to your IDE. If that works, you need only to set the path mapping within your PhpStorm IDE to be able to debug properly.

<?php xdebug_break(); 

If everything works

Your IDE looks like below, if you have setup everything properly:


Now you can use the following Drush command to debug your code.

drush php-eval 'my_nice_function()'

Drupal will be booted up and you can inspect your code during the application runtime. This approach is faster then locating a certain page on your Drupal site for finding the entry point to your code or using the Devel module with it's webpage based PHP execution functionality at http://my-website.dev/devel/php.

Tip: Check out the Phing build tool which is written in PHP

I recommend to create a command with your favorite build tool (I recommend https://www.phing.info/) to quickly disable and enable XDebug. So that you execute "xd" for disabling and "xe" for enabling to save time.


Debugging PHP CLI scripts in PhpStorm which are running inside a remote server

Submitted by Peter Majmesku on Mon, 08/29/2016 - 20:18

Please notice: This article is for debugging with Xdebug. Not any "old-fashioned" debugging with var_dump(); or print_r() or any other "90ies webmastering style".

Remote debugging by SSH tunnel and the PhpStorm debugger

Additional settings in /etc/php5/cli/php.ini:


 Then connect to your server via SSH tunnel (I have used a Vagrant box as an example, but you can tunnel into any server):

ssh -R 9000:localhost:9000 username_goes_here@hostname_goes_here

Start a script via PHP from the command line and PhpStorm will react (debugging button in PhpStorm must be turned on and the mapping for the directories must be set).

Remote debugging by the PhpStorm tools

In case that the debugger window will be opened, but the execution point will not be shown, you can run the script from PhpStorm itself.
Firstly you have to set up the remote debugging (Preferences > Languages & Framework > PHP). Choose here a remote interpreter.

PhpStorm Settings

If you have not already done so, set it up. The "SSH Credentials" settings have worked for me. While I'm using Vagrant and PhpStorm has an extra Vagrant checkbox (which has not worked for me):

PhpStorm Settings

In your PHP command line programs you need to specify often arguments. That can be done also:

PhpStorm Settings
Subscribe to Xdebug