var_dump() function can take you a long way in debugging if you need sometimes to check the value of the variable. Sooner, or later you will run into a situation where "proper" debug tools are required to find out how your code is executing.
Keep in mind this article is based on OSX, PhpStorm (get started guide), Laravel Homestead for development environment. Depending on your OS, or tools used you might need to make small changes to make this work. This GitHub repository is used in this article.
Skip to any of the sections, or continue reading:
- Start debug session in browser
- Debugging in PhpStorm
- Debugging CLI scripts
- Manually changing Xdebug PHP configuration
Laravel Homestead ships with Xdebug installed, and configured.
If you're not using Homestead check the article on how to get started with it.
If you don't want to use Homestead check the documentation of Xdebug for options on how to install it.
Start debug session in browser
If you don't want to use the browser add-on, you will need to set
XDEBUG_SESSION_START=session_name as: URL parameter,
POST parameter, or cookie. To stop the debugging session you need to use
XDEBUG_SESSION_STOP URL parameter, or to delete the cookie.
Debugging in PhpStorm
From PhpStorm preferences (
⌘,) go to
Languages & Frameworks | PHP. Create (or select) the remote interpreter based on Vagrant.
Run | Start listening for PHP Debug Connections command from the menu to start the debugging session. After you finished debugging use
Run | Stop listening for PHP Debug Connections command to stop debugging session. For easier access you might want to set a keyboard shortcut which executes both commands (e.g.,
After loading the page (with debug session turned on) if debugging is not configured PhpStorm will throw a prompt with auto-configuration values. Accept to create a new server configuration.
From PhpStorm preferences (
⌘,) go to
Languages & Frameworks | PHP | Servers, select the newly created server. Configure the main project directory (on host) to point to the directory on the remote machine (use
pwd in Vagrant terminal to find it).
Then open the file you want to debug, add a breakpoint on the line of the code to pause execution on (click on a line number in a gutter). Reload the page, and the script execution should stop before the breakpoint. You should see the window with variables, and actions for debugging (e.g., terminate, run, step into, step over, resume program, stop). You can make breakpoints conditional to only pause on specific cases.
Debugging CLI scripts
Xdebug for CLI scripts is not enabled by default (run
php -v to see if it's enabled).
For convenience there are two aliases that enable/disable Xdebug:
# enable xon # disable xoff
Those aliases expand to the following commands (notice that you might need to provide PHP version with
# enable sudo phpenmod -v7.1 -s cli xdebug # disable sudo phpdismod -v7.1 -s cli xdebug
You will also need to set two environment variables (it should be automatically set inside
.bash_extra file on provisioning, make changes if needed):
export PHP_IDE_CONFIG="serverName=www.homestead-article.dev" \ XDEBUG_CONFIG="idekey=phpstorm remote_host=192.168.10.1"
serverName value should be taken from your Homestead configuration
The rest is the same as when debugging a web script, add the breakpoint, start listening to debug session, run the command, make debug actions.
Manually changing Xdebug PHP configuration
The development environment should have all the configurations for debugging. If for some reason you need to make changes you can find configuration files at
/etc/php/PHP_VERSION/INTERFACE_TYPE/conf.d/20-xdebug.ini (note that
INTERFACE_TYPE are placeholders). For PHP 7.1 FPM (web interface) configuration the file will be at
/etc/php/7.1/fpm/conf.d/20-xdebug.ini, and for CLI the file will be at
At the least your configuration should contain the following lines:
xdebug.remote_enable = 1 xdebug.remote_connect_back = 1 xdebug.remote_port = 9000
Restart the PHP if you updated the FPM configuration:
sudo service php7.1-fpm restart