Learn how to make Xdebug work withing Laravel Homestead with PHPStorm
If you want to skip a small introduction for Xdebug and Homestead, got straight to Syncing Xdebug, Homestead and PHPStorm
To better understand a problem at hand when facing a bug or creating a feature we should be using tools that help debugging. One of those tools for the PHP world is called Xdebug. This tool is an extension to the PHP executable that observes every request made to one PHP application and is able to tell us lots of useful data regarding request parameters, server variables, program objects instantiated and current values for each and every one of those and some more.
Laravel Homestead is a CLI application that generates a Vagrant (tool to run operating system from the command line inside other operating system) configuration that we can use and is better tailored for Laravel applications. However, with some tweaks - depending on the application - we can make it work for any PHP code.
The configuration it provides helps replicating equally in all computers of developers of a team. This way, in theory, one code that works in one developer machine will also work in another developer machine, allowing better workflows of development and bug fixing. This configuration is also responsible to install/bring by default Xdebug, which we can enable and use it to debug our code.
As Homestead is another (guest) operating system inside the actual operating system we run (host), the code of our application inside of it is treated as remote code. This means that, for our debugging purposes, it's like the code is in another machine that we need to connect to in order to know more about it. As such, we need to sync Xdebug extra information from within Homestead to our PHPStorm installation on our host. To do so, we have a few steps to follow:
You can find where it is located by running
php --ini | grep xdebug which you show a path where the configuration resides. It may be needed to use escalation of privileges to run the process by using
sudo to open given path, like
sudo vim <path-to-xdebug-ini>.
Inside the Xdebug configuration, paste the following content:
zend_extension=xdebug.so xdebug.remote_enable = 1 xdebug.remote_autostart=1 xdebug.remote_host=10.0.2.2 xdebug.remote_port = 9100 xdebug.remote_log=/home/vagrant/output.txt
A short explanation of this configuration:
After making those changes, save the file, quit the editor you're using and restart the PHP service loading given Xdebug configuration, like
sudo service php-7.1-fpm restart or the corresponding method of your choice (e.g.,
You can verify if your PHP has Xdebug attached by running
php -v and looking for Xdebug credits information on the output, like
PHP 7.1.26-1+ubuntu18.04.1+deb.sury.org+1 (cli) (built: Jan 11 2019 14:13:49) ( NTS ) Copyright (c) 1997-2018 The PHP Group Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies with Zend OPcache v7.1.26-1+ubuntu18.04.1+deb.sury.org+1, Copyright (c) 1999-2018, by Zend Technologies with Xdebug v2.6.1, Copyright (c) 2002-2018, by Derick Rethans with blackfire v1.24.3~linux-x64-non_zts71, https://blackfire.io, by Blackfire
In PHPStorm we have a few places to configure, namely: Settings > Languages & Frameworks > PHP > Debug; and Settings > Build, Execution, Deployment > Deployment.
Ignore external connections through unregistered server configurations
Break at first line in PHP Scripts
And for the other we do the following:
+button and select
SFTP, and give it a name
/home/vagrant/<place where your code lives>(normally would be
Send keep alive messages each:
Select a file where you would like to debug, add a breakpoint to it by clicking on the left gap between the line numbers and the code area itself so you can see a red dot. PHPStorm, when communicating to Xdebug will check if the PHP code reached that specific line and if so will halt the execution so we can check the current variables, objects and properties of the request and application.
Before being able to listen for debug messages, we need to tell the browser to send an extra information, via get parameter on the request, so PHPStorm knows that request should be checked. We do that by adding
http://local.application.test/?XDEBUG_SESSION_START=PHPSTORM. Press end to access the page so the parameter is saved to the session.
After that, we can go to PHPStorm and tell it to start listening for connections by pressing the button that looks like a telephone, close to the ones where we see a play button and a bug button. When PHPStorm is not listening for debug connections this telephone button will have a small red crossed circle in it. On the other hand, while listening we see 3 small arcs instead of the small red crossed circle.
Now, refresh the page, wait a moment and you should be able to see that PHPStorm has halted the PHP process and has a yellow background on the line that had the breakpoint (red dot) and opened a new area containing information regarding the current debugging request, with the current scope, objects, global variables and the likes.
If you like this post, let me know through Twitter (@erickpatrick)