Jiga

Vagrant Remote Debugging – Xdebug 3 & IntelliJ or PHPStorm

Debugging is one of the most efficient ways to investigate an unexpected behaviour. This post details how to setup a debugger for a PHP application running in a vagrant machine via your IDE such as IntelliJ or PHPStorm. We’ll be using Xdebug version 3 in this post. Xdebug version 3 is significantly different from the previous version 2 in terms of configuration. I am using CakePHP in this post, but the steps are same for any framework or even without a framework at all.

Xdebug Setup

Install PHP & Xdebug:

This instruction is for Ubuntu. For other OS, go to the official guide.

add-apt-repository ppa:ondrej/php
apt-get update
apt -y install php7.4 php7.4-fpm php7.4-xdebug

Verify if Xdebug is installed and its version. You should see Xdebug in the output of php -v.

vagrant@dev:~$ php -v
PHP 7.4.28 (cli) (built: Feb 17 2022 16:06:19) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.28, Copyright (c), by Zend Technologies
    with Xdebug v3.1.2, Copyright (c) 2002-2021, by Derick Rethans

You should also verify via phpinfo() as the configuration files could be different for CLI and FPM processes:

Once you have verified Xdebug is installed, you can start setting up the remote access configuration. Update the content of the 20-xdebug.ini from the above highlighted location to this:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=10.0.2.2
xdebug.client_port=9003
xdebug.show_error_trace = 1

10.0.2.2 is the IP of your host. You can get this IP by running this command from inside the vagrant machine:

vagrant@dev:~$ netstat -rn | grep "^0.0.0.0 " | cut -d " " -f10
10.0.2.2

9003 is the default binding port for Xdebug 3. After updating the configuration run service php7.4-fpm restart to make sure the new configuration is picked up.

The new configuration can be verified via phpinfo() again:

IDE Setup – IntelliJ or PHPStorm

Remote Interpreter

Open the IDE settings -> Languages & Frameworks -> PHP -> Add a new CLI interpreter. This step is required if you want to debug CLI PHP scripts instead of web pages. More instructions on this further down below.

Ensure that ‘Debugger: Xdebug 3.1.2’ is shown.

Server setup

Now go to PHP -> Server and setup a new server. Specify the project files and include files as well. This step is required by the IDE to map the files from your local system with the files used by the server which is in vagrant.

Debugger Setup

You can modify these settings as per your wish. It is good to have the two ‘Force break` options as it helps identify any misconfiguration with Xdebug.

Browser Setup

Firefox extension and Chrome extension. This will send a special cookie in all web requests and helps the IDE bind to that.

Click this icon to start listening to PHP web requests for debugging:

Verify

With all the setup done, we can verify via IDE’s ‘Validate’ function. Click ‘Validate’ from the ‘Pre-configuration’ section from PHP -> Debug section.

Path should be the location where the IDE can create a test script. This is usually the public path which has the index.php or bootstrap.php. URL is your web server URL from the host.

Once the configuration is verified, it’s time to debug something!

Place a breakpoint in your IDE and load an URL and see the breakpoint is hit like this:

You can now use ‘Watches’, debug variables and evaluate expressions and do a lot more.

Debugger also works when you want to run CLI scripts from the vagrant machine. Remember the ‘Remove Interpreter’ we setup earlier. We’ll use that now.

Debugging CLI scripts

Create a new ‘Run/Debug Configuration’ using ‘PHP Script’ as the template and fill these values. Ensure the ‘Interpreter’ is set to the ‘Remove Interpreter’ we created earlier.

Change the File value to match the PHP script you want to run. And now click the ‘Debug’ icon and any breakpoints set within the code for this script will be hit.

Happy debugging!