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.
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
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
IDE Setup – IntelliJ or PHPStorm
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.
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.
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.
Click this icon to start listening to PHP web requests for debugging:
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
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.
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.