The simple 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:

• Installation
• Start debug session in browser
• Debugging in PhpStorm
• Debugging CLI scripts
• Manually changing Xdebug PHP configuration

Installation

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

Use FireFox add-on, or Chrome extension to enable the debug session of a web page. After enabling load the page you want to debug.

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.

Use 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., ⌥⇧D).

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 -v option):

# 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"

The serverName value should be taken from your Homestead configuration sites.map property.

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 PHP_VERSION, and 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 /etc/php/7.1/cli/conf.d/20-xdebug.ini.

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