Set Up xDebug, with Homestead, PHPStorm and PHP7

This tutorial will guide you through the process of installing xDebug on your Homestead box, and configuring PHPStorm to listen for xDebug connections from Homestead. Please let me know in the comments if you have any issues, and I’ll do my best to help out!

You will need to have Homestead/Vagrant set up and running. In case you don’t, click here to go to Laravel’s beautiful documentation and set it up first.

An overview of the tasks we will be performing:

• Install xDebug on Homestead (it no longer comes installed).
• Configure xDebug.
• Install Chrome xDebug plugin.
• Configure PHPStorm.

Install xDebug on Homestead

SSH into your virtual machine by issuing the following terminal command from your Homestead directory.

vagrant ssh

Copy the output of the following command and paste it on xDebug’s website. Follow the instructions there to install xDebug.

php -i

Configure xDebug

Now that xDebug is installed, we’ll need to add some configurations. Vim is my editor of choice.

sudo vim /etc/php/7.0/fpm/conf.d/20-xdebug.ini

Add the following lines to this file. Make sure your zend_extension path is correct, as it may not match mine. *

zend_extension = /usr/lib/php/20151012/xdebug.so
xdebug.remote_enable = 1
xdebug.remote_connect_back = 1
xdebug.remote_port = 9000
xdebug.scream = 0
xdebug.cli_color = 1
xdebug.show_local_vars = 1

Save the file by hitting escape and typing :wq

1. Restart php by issuing sudo service php7.0-fpm restart

• You may optionally want to add xdebug.remote_autostart=1, which will automatically start xDebug without the need for a Chrome plugin as long as this is selected. This is probably not something you want to do, as I can guarantee it will get annoying, however, if for whatever reason you need this you do have the option.

Install Chrome xDebug plugin

I highly recommend using this Chrome plugin. Just install it and you’re good to go.

Configure PHPStorm

1. Go to preferences. Click PHPStorm / Preferences.
2. Go to Languages & Frameworks / PHP / Servers
3. Click the + button to add a new server.
4. Name your server, add your localhost, set it to port 80, and use xDebug as your debugger. (See picture under)
5. Check Use path mappings bug. Add the Absolute path on the server for the root directory and the public directory. (See picture under)
6. Click Apply / OK

Usage

1. Add breakpoints into your code and set PHPStorm to listen to incoming connections.
2. In your browser, enable the xDebug plugin, and navigate to the page you want to debug. In other words, follow the steps to reach the breakpoint you added.
3. When the breakpoint is reached, you will automatically be taken to PHPStorm. From there you have a bunch of tools to help you debug. You can navigate the execution using Step Over, Step Into, Step Out blah blah blah. You can evaluate expressions, read and set variables at runtime (how cool is that?), and you can set conditional breakpoints.

Testing and Getting Started

• Add a breakpoint to the first line of code in your routes file. You can add a breakpoint by clicking on the grey bar next to the line number.

• Click Run / Start Listening for PHP Debug Connections.

• Open a new tab in your browser, enable the xDebug plugin and navigate to your home page. If you’re on a Mac, you can easily turn the plugin on or off by pressing alt + shift + x.

• Once you hit the breakpoint, you will be taken to PHPStorm, and that’s where the magic begins. Now you can run your code line by line, and see exactly what is going on, tweak the variables, and fully understand your code fast and easily, without the need to use die and dump statements. (See picture below)

TIP: You will need to stop an xDebug session if you don’t get to the response part, otherwise your local site will not work. This is because it is waiting for a response from PHPStorm, as you’re in the middle of a debugging session. So hit the stop button to the left. If you’re on a Mac, you can use command + F2.