How to Setup Xdebug in Homestead and PHPStorm
Fixing and debugging code issues with debug mode will make your life much easier as a developer. I always do it at work and on my projects regardless of programming language or frameworks, and every developer should know how to debug issues with any debugger.
If you are working with PHP or Laravel projects like me, one of the most popular debuggers out there is Xdebug. In this guide, you will learn how to correctly set up Xdebug in Homestead and create debug configuration in your PHPStorm IDE.
Configure Xdebug in Laravel Homestead
The latest build of Laravel Homestead has Xdebug already installed, you just have to correctly configure it and make sure it is running and ready to accept connections. If you don’t have Homestead yet, you can follow the official documentation about installing it in your machine.
Create or update the target Xdebug config file depending on the PHP version that your project is supporting.
# for PHP 7 versions
sudo vim /etc/php/7.x/fpm/conf.d/20-xdebug.ini# for PHP 8 versions
sudo vim /etc/php/8.x/fpm/conf.d/20-xdebug.ini
Use the following example configuration which has an ide key configuration for better filtering of callbacks in PHPStorm when it is in debugging mode and active listening for the connection on a specific port.
Save the configuration and restart the php fpm service.
# for PHP 7 versions
sudo service php7.x-fpm restart# for PHP 8 versions
sudo service php8.x-fpm restart
Check if Xdebug is running by executing the PHP CLI command with the version option.
If you do not see the Xdebug version in the CLI output, it is likely that the Xdebug is not running. You can execute the aliased function that is included in the Laravel Homestead to run Xdebug.
You can turn off Xdebug by executing the off command alias of Homestead.
At this point, your Xdebug is all set! You can refer to the official documentation for more details on debugging and profiling in Laravel Homestead.
Install Chrome Xdebug Plugin
Assuming you are using the chrome browser for development, installing the Xdebug helper chrome extension is recommended.
To debug PHP applications in PHPStorm, PHP server settings and debug configuration are needed.
PHP Server Settings
- Go to PHPStorm preferences / settings.
- In the PHP Section, go to servers.
- Add a PHP server and provide the server, host, and port. In the host field, set the IP or the local domain of the homestead and then use port 80 (since we want to debug routes for now).
- Check the “Use path mappings” and then add the absolute path of the target project from the homestead like the example above.
- Lastly, click apply or ok.
- To add debug configuration, click “Run”, and then “Edit configurations..”.
- In the Run/Debug Configurations window, click the “+” and choose PHP Remote Debug.
- Set the name, check the “Filter debug connection by IDE key” checkbox, select the server you just created previously, and provide the ide key configured from the Xdebug configuration of the homestead.
Usage and Testing
At this point, you should be all set to debug any PHP or Laravel application. Let’s start debugging by selecting the debug configuration that we have just created as the run configuration and then make sure that PHPStorm is listening for debugging connection.
Place debug breakpoints in the lines of code you want to debug, and click the debug mode button.
Finally, load the page to be debugged in the browser, and do not forget to enable the Xdebug chrome extension. Immediately you will notice that PHPStorm will pause at your breakpoint, indicating that it has successfully listened to the incoming debug connection.