Every two weeks I send out a newsletter containing lots of interesting stuff for the modern PHP developer. You can expect quick tips, links to interesting tutorials, opinions and packages. Want to learn the cool stuff? Then sign up now!

Setting up Xdebug with Laravel Valet

On most of my day to day work I use Laravel Valet to develop locally. When hitting a bug often I just put a dd() statement in the code to quickly inspect what’s going on. But when encountering a complex bug this becomes tedious. Wouldn’t it be nice if we could add a breakpoint to our code and be able to inspect the values of all variables in one go (and even execute the script line by line)? Enter Xdebug. In this post I’ll show you easy it is to install and use it.

Installing Xdebug

I’m going to assume that you have are running macOS, have latest version of PHP installed together with homebrew.

To install xdebug, just run this command:

brew install php71-xdebug

In the last lines of the output of the installation indicated that there’s a new ini file created at /usr/local/etc/php/7.1/conf.d/ext-xdebug.ini. By running php --ini you can verify that php is reading that setting file.

Go ahead and add these lines to that file:

xdebug.remote_enable=true
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_handler=dbgp

The above settings are needed to allow PHPStorm to connect to Xdebug. You can look up the meaning of the individual settings in the xdebug documentation. Port 9000 seems to be the default, but you may choose another port if you like.

Debugging a cli command

If you want to follow along with the rest of this post, create a fresh copy of laravel in a directory you parked with Valet. In my mac I’ve parked the /Users/freek/dev/sites directory. In that directory I ran laravel new laravel to create fresh copy of Laravel in the laravel directory.

Let’s first test out if we can add a breakpoint to a script that is running on the command line. Open up the newly created project in PHPStorm. In the Debug preferences in PHPStorm make sure the debug port is set to the same value you specified in the ini file. Also uncheck “Force break at the first line when a script is outside the project”.

Next up, select “Start listening for PHP Debug Connections” from the “Run” menu.

Let’s add our first breakpoint. Open up routes/console.php and add a breakpoint by adding click in the sidebar left on the $this->comment(... line.

Now let’s run the command in which we just place a breakpoint. Got to the command line and execute php artisan inspire. And boom, xdebug should activate.

In the variables pane you can now inspect every single variable in the script. In the console pane you can run arbitrary code. Handy! Explaining the Xdebug UI in PHPStorm is out of scope for this article. Read the PHPStorm docs to know more or just play around with it.

Debugging a web request

In order to trigger Xdebug a special cookie needs to be set on the webrequest. You can use the bookmarklets provided by Jetbrains to set those cookies. Personally I prefer using the Chrome Xdebug Helper extension.

With the extension installed just point your browser to your site, click on the little bug icon next to the address bar, and choose “Debug”.

That bug icon should turn green now indicating that the right cookies have been set. Now go to the a piece of code in your project that should run when the web request is performed. In my case I’m going to set a breakpoint in web/routes.php. When refreshing the webpage you should first see this dialog indicating that PHPStorm got an incoming connection from Xdebug.

After clicking “Accept” you should hit your breakpoint.

Congratulations on your working Xdebug installation!

A word on performance

With Xdebug enabled your PHP code will run a lot slower. Luckily Djamil Legato coded up an xdebug toggler make it easy to switch xdebug on and off with a single command.

You might see this warning when running composer:

You are running composer with xdebug enabled. This has a major impact on
runtime performance.

To solve that just update to the latest version of composer which can automatically detect and temporarily turn off Xdebug while it’s running.


If you had trouble following this guide, you might take a look at this video by Gary Hockin. He dives a little bit deeper in the Xdebug integration in PHPStorm.

Happy debugging!

Freek Van der Herten is a partner and developer at Spatie, an Antwerp based company that specializes in creating web apps with Laravel. After hours he writes about modern PHP and Laravel on this blog. When not coding he’s probably rehearsing with his kraut rock band. He loves waffles and butterflies.
  • iboinas

    Hey Freek!
    Maybe good to add the
    export XDEBUG_CONFIG=”remote_enable=1 remote_mode=req remote_port=9000 remote_host=127.0.0.1 remote_connect_back=0″
    on the .zshrc or .bash_profile, for newcomers
    Happy coding!

  • So after using the xdebug toggler I cant get Laravel Valet working anymore?

    Any ideas?

  • besrow

    I tried to use it with sublime text3, but my breakpoint are not “breaking”. The configuration is supposed to be basicly the same at least for the xdebug part, but I assume something might be missing, if you have any hint please.

    • besrow

      I changed the config to port 9001, as I read something about a conflict with valet port which can use 9000 and it works

  • Pingback: Laravel Valet enable xdebug with PHPStorm - Ken Teo's Blog()

  • Rob Mazur

    If you’ve gone through all the guides/tutorials and are still having issues getting PhpStorm to debug try checking the PHP version linked to your Valet install. Spent hours struggling only to realize everything was configured correctly for PHP 7.1, but Valet was still running 7.0! I had checked using php -v and version looked right, but not until checking phpinfo() did I realize app was running on old version. Used this article to change Valet: https://dyrynda.com.au/blog/switching-php-versions-with-laravel-valet Want to put it out there to hopefully save someone else some time 🙂