Configuring debugging in Vagrant

Edit on GitHub

This article describes how to configure debugging in your development environment.

To configure debugging for the VM below version 91, see Configuring debugging in Vagrant with VM below version 91.

Installing the Xdebug module

To install the Xdebug module:

  1. Install Xdebug:
sudo -i apt-get install php-xdebug
  1. Enable Xdebug by updating /etc/php/7.4/mods-available/xdebug.ini with the following:

Xdebug v3

 xdebug.mode=debug
 xdebug.client_host=10.10.0.1
 # This is needed to prevent max recursion exception when Twig templates are very complicated
 xdebug.max_nesting_level=1000
 # Disable Opcache to avoid IDE issues
 opcache.enable=0
 opcache.enable_cli=0

Xdebug v2

 xdebug.remote_enable=1
 xdebug.remote_host=10.10.0.1
 # This is needed to prevent max recursion exception when Twig templates are very complicated
 xdebug.max_nesting_level=1000
 # Disable Opcache to avoid IDE issue
 opcache.enable=0
 opcache.enable_cli=0
  1. Enable module and restart PHP-FPM:
sudo -i bash -c "phpenmod xdebug && systemctl restart php7.4-fpm.service"
Heavy memory usage

After you’ve finished debugging, make sure to disable the module by running the following command:

sudo -i bash -c "phpdismod xdebug && systemctl restart php7.4-fpm.service"

Configuring servers

Define servers in PhpStorm:

  1. In PhpStorm, go to Preferences > Languages & Frameworks > PHP > Servers.
  2. Add a new server:
    1. Select +.
    2. Enter a Name. For example, zed.mysprykershop.com (it is used in CLI below).
    3. For Host, enter ~^zed\.de\..+\.local$.
    4. Select Use path mappings.
    5. For Absolute path on server, select /data/shop/development/current.
  3. Add another server for Yves. Copy the settings from the previous step, but, for Host, enter ~^www\.de\..+\.local$.

Configuring debugger

  1. In PhpStorm, go to Preferences > Languages & Frameworks > PHP > Debug.

  2. In the External connections section, for Max. simultaneous connections, select 2.

Now you can debug Zed through a connection from Yves.

Debugging

To debug with PhpStorm:

  1. Go to Run > Edit Configurations….

  2. Add a PHP Remote Debug:

    1. Select +.
    2. Enter a Name.
    3. For Servers, enter zed.mysprykershop.com.
    4. For Ide Key(session id), enter PHPSTORM.
  3. Select Listen for PHP Debug Connections listen-to-php-debug-button.

  4. Select Debug debug-button. You should get the message: “Waiting for incoming connection with IDE key ‘PHPSTORM’”.

Debugging console commands

To trigger Xdebug in CLI, prepend environment variables to commands as follows.

XDEBUG_CONFIG="remote_host=10.10.0.1" PHP_IDE_CONFIG="serverName=zed.mysprykershop.com" vendor/bin/console <command>

The value of serverName should reflect the server name you’ve entered when configuring servers.

Configuring a Google Chrome helper for Xdebug

As a Chrome user, you can optionally configure the Xdebug helper extension as follows:

  1. Add Xdebug helper to the browser.
  2. In the extension settings, for IDE Key, select PhpStorm.

Now you can manage debugging sessions in the browser toolbar.

Configuring browser bookmarklets for Xdebug

To manage debugging sessions directly in a browser, configure browser bookmarklets as follows:

  1. Generate helper bookmarklets.
  2. Bookmark the generated links.

Now you can manage debugging sessions using the bookmarks you’ve created.