Configure Xdebug on hypernode-vagrant

in Tools

Xdebug is a debugger for PHP. It can be used to retrieve extended debug information and stacktraces from your development environment and send it to a log file or to your IDE or browser. As Xdebug has a massive performance impact, it’s not possible to use this debugger on the hypernode itself.

Xdebug is installed on hypernode-vagrant. In this article, you can find how to configure xdebug to send stacktraces and debug logs to your local IDE.

To install a newer version of Xdebug, refer to the article about installing Xdebug

Debugging HTTP requests

Step 1: Configuring Xdebug in /data/web/public/.user.ini

Enable Xdebug for multiple machines

First, create a php config file in /data/web/public/.user.ini:

xdebug.show_error_trace = 1
xdebug.remote_enable = 1

# Debug from multiple machines
xdebug.remote_connect_back = 1
xdebug.remote_addr_header = HTTP_X_REAL_IP
xdebug.remote_port = 9000
xdebug.scream = 0
xdebug.show_local_vars = 1
xdebug.idekey = PHPSTORM

The xdebug.remote_addr_header = HTTP_X_REAL_IP configuration is used because when xdebug.remote_connect_back is enabled, Xdebug will try to connect to the client that made the HTTP request.
It checks the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables to find out which IP address to use.
The problem is that $_SERVER['HTTP_X_FORWARDED_FOR'] may contain more than one IP address in which case Xdebug wont’t be able to connect back.
By configuring xdebug.remote_addr_header we make sure Xdebug checks the $SERVER variable with the configured name before the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables.

Enable Xdebug for one single machine

If you only want one specific machine to be able to debug your application you should use the xdebug.remote_host option. This variable should contain the IP address of the host machine running the IDE.

The easiest way to retrieve this ip address is to surf to the shop from the machine your IDE is running on and look at the $_SERVER variables.

You should be able to determine your IP address from one of the following variables:

  • $_SERVER['HTTP_X_FORWARDED_FOR']
  • $_SERVER['REMOTE_ADDR']
  • $_SERVER['HTTP_X_REAL_IP']

(Ignore any 127.0.0.1 or ::1 address.)

If xdebug.remote_connect_back is enabled the xdebug.remote_host is ignored.

xdebug.show_error_trace = 1
xdebug.remote_enable = 1

# Debug from 1 specific machine (Disable xdebug.remote_connect_back for this to work.)
xdebug.remote_host = IP.address.from.host
xdebug.remote_port = 9000
xdebug.scream = 0
xdebug.show_local_vars = 1
xdebug.idekey = PHPSTORM

Step 2: Restart services

Restart php-fpm and nginx to ensure these changes are loaded immediately.

Login as user vagrant:

vagrant ssh

Restart php-fpm and nginx:

sudo su
sudo service php5-fpm restart
sudo service nginx restart

Step 3: Disable ‘Break at first line’ settings in PHPStorm

You can disable these settings under:

Settings > Languages & Frameworks > PHP > Debug > External Connections AND Settings > Languages & Frameworks > PHP > Debug > Xdebug

phpstorm-preferences-window

If you don’t do this you’d get an error like this:

Remote file path '/usr/lib/hypernode/fpm-inspector/prepend.php' is not mapped to any file path in project

Step 4: Activate Xdebug

In order to activate the debugger, you need to set a special GET/POST or COOKIE parameter (More info).

You can start debugging manually, but it’s much more convenient to use one a special tool such as browser toolbar or bookmarklet to do that.

For more info, refer to the jetbrains documentation about PhpStorm

Step 5: PhpStorm configuration and mapping

In PhpStorm toggle the “Start Listening for PHP Debug Connections”-button.

Set a breakpoint in your code.

Surf to a page on your webshop (that involves the code where you put your breakpoint.)

If all goes well, PhpStorm will show you the following popup window indicating that Xdebug is trying to connect to your IDE.

Select: “Manually choose local file or project” and click ‘Accept’.

phpstorm-incoming-connection-window

Step 6: Start debugging

Reload the page and start debugging!

Debugging CLI scripts and n98-magerun plugins with Xdebug

Step 1: Define the IP of your host machine.

Contrary to debugging an HTTP request, debugging a CLI commands requires you to tell Xdebug explicitly on which machine our IDE is running in order for it to connect to it.

Easiest way to do this is to surf to the shop from the machine your IDE is running on and look at the $_SERVER variables.

You should be able to determine your IP address from one of the following variables:

  • $_SERVER['HTTP_X_FORWARDED_FOR']
  • $_SERVER['REMOTE_ADDR']
  • $_SERVER['HTTP_X_REAL_IP']

(Ignore any 127.0.0.1 and ::1 address.)

Step 2: Disable “Break at first line” settings in PHPStorm

You can disable these settings under:

Settings > Languages & Frameworks > PHP > Debug > External Connections AND Settings > Languages & Frameworks > PHP > Debug > Xdebug.

If you don’t do this you’d get an error like this:

Remote file path '/usr/local/bin/n98-magerun' is not mapped to any file path in project

For images refer to the section Break_at_first_line in “Debugging HTTP requests” above.

Step 3: Building the CLI command

Place a breakpoint in your code, prepend the CLI command with the necessary Xdebug config and run it:

XDEBUG_CONFIG="remote_enable=1 remote_host=IP.address.from.step.1 idekey=PHPSTORM" n98-magerun sys:cron:run

Or, alternatively you can create a n98-magerun-xdebug alias by adding the following line to your ~/.bashrc file:

alias n98-magerun-xdebug='XDEBUG_CONFIG="remote_enable=1 remote_host=IP.address.from.step.1 idekey=PHPSTORM" n98-magerun'

The aliased command will be available on any new terminal.
To have the aliased command on any existing terminal one need to source ~/.bashrc from that terminal as:

source ~/.bashrc

Step 4: PhpStorm configuration and mapping

If all goes well, PhpStorm will show you a popup window indicating that Xdebug is trying to connect to your IDE.
Select ‘Manually choose local file or project’ and click ‘Accept’.

Step 5: Start debugging

Run the command again as described in step 3 and start debugging!

Troubleshooting

  • Problem: The command runs but the debugger doesn’t stop at your breakpoint! Instead the following message appears in your PhpStorm event log:
Debug session was finished without being paused.
It may be caused by path mappings misconfiguration or not synchronized local and remote projects.
To figure out the problem check path mappings configuration for 'local' server  at PHP|Servers 
or enable "Break at first line in PHP scripts option (from Run menu)

phpstorm-error-output

Solution:

  • Click the PHP|Servers link.
  • Rename the server so that you might recognize it easier in the future.
  • Select the “Use path mappings”-option as the Vagrant Hypernode is considered a remote server.
  • Map your local public folder to ‘/data/web/public’ in the column “Absolute path on the server”.
  • Click “OK”

phpstorm-path-mappings

Problem: My settings in my .user.ini are not getting picked up by PHP
Solution:

  • Restart php-fpm (as user vagrant): sudo service php5-fpm restart or for PHP7: service php7.0-fpm restart

Problem: I don’t receive any events from Xdebug
Solution:

Chances are that on the remote ip that you are sending events to, no xdebug instance is listening.
This is mostly caused by an incorrect xdebug.remote_host configuration.

Find out your remote ip by adding the following snippet to your /data/web/public directory as ip.php on your vagrant node:

<?php echo $_SERVER['REMOTE_ADDR'];

And after that, request it through a browser or using curl:

curl http://hypernode.local/ip.php

Now edit your .user.ini and change xdebug.remote_host to the output of the snippet above.

This article has been written by Tjerk Ameel, Magento Developer at Indie Group

0