Setting up Laravel, PHPStorm and Xdebug… with a local server

Quickstart to the magic of debugging.

Photo by Alex Perez on Unsplash

When developing your next project, sometimes it’s better to just start using the Laravel Built-in Server by calling php artisan serve. This is just a nice wrapper for the PHP Built-in Server that its up in seconds and just works, compared to building or downloading a LAMP/WAMP/MAMP stack that may takes more time to download, install and setup.

I mean, it’s more cleaner to download PHP to somewhere in your PC, put the folder on the PATH variable of your OS, (in some cases restart) and you’re set. Even using SQLite until you need to use the a production-grade RDBMS like MySQL, MariaDB, PostgreSQL or Microsoft SQL Server once your project is putting his two foots in a real database.

One of the fun parts of creating your application is to debug, and trace a Request from the start for the finish, seeing what methods hit and what is missed, check variables, and so on.

Doing this with var_dump(), dump(), or dd() is a cheap way to know what your code is doing, but… what if it were a better way? Like… “I want to see what really happens here”, refresh the page and boom, you know.

I’m gonna link you to see a nice Laracast video for Xdebug and its magic, which also includes the installation instructions. Come back here when you are ready. Take your time, this article is going nowhere.

Setting up your Local Server

If you haven’t set your Local Server, then this is the time. First, go to the menus, hit “Run” → “Edit Configurations…”.

You will be presented with a lot of templates to edit. Press the “+” button in the corner. You will see a list of templates to base your own configuration.

If you have the LaravelStorm plugin installed, you can just pick “Laravel”.

Otherwise you will have to select “PHP Built-in Web Server” and configure the server manually — practically the same thing but with some additional steps. You will have to do the following:

1. Put the host as “localhost” (unless you plan to use a custom loopback domain) and 8000 as the “port” (unless you decided for other number).
2. Add the /public path of your project into the “Document root”.
3. Put the server.php file as the router script. This is used by Laravel to simulate Apache mod_rewrite.
4. Set the “Custom Working Directory” to your project root.

If done correctly, you should have something like this.

Don’t worry about the error, I just used a bogus path for this article.

Now, double check that “Allow parallel run” in the corner is disabled, and “Activate Tool Window” is also disabled as the window doesn’t have very useful purposes.

You can use “Laravel Built-in Server” as the name of this configuration since it’s more descriptive.

Now that our Local Server is ready to run, we need to make it debuggable.

Setting up the debugger session

PHPStorm comes with a handy Debug configuration called “PHP Web Site”, which was called “PHP Application” on older versions. When properly run, it will create a debug session in the browser and then hear any debug instruction incoming automatically.

What this does backstage is very simple: it opens a browser with an special parameter shared by PHPStorm that tells Xdebug to create a debugging session, which is latter heard by PHPStorm.

Let’s create a “PHP Web Site” and input the same address and port we used to create our Local Server.

If you’re using the Laravel Built-in Server, you can add to the “Before launch” this configuration. This will make that, every time you run the Debugger session, the server is up.

Now, about that red text. Click the dotted button and you will see an empty list of Server to select. Just create one with the same settings you used for your Built-In Server:

Additionally, check the “Use path mappings”. You will see a list, starting with your Project Path. In the “Absolute path on the server”, parallel to your project path, just click it and select the same path. That’s it.

Save it as “Debugger” and hit “OK”. Welp, you can name it as you want anyway.

Hearing Xdebug magic

If we start the Debugger using the bug icon, the Built-in Server will start automatically. But there is a slight problem: PHPStorm doesn’t hear any connection from Xdebug! No problem, just enable it in the “Run” menu.

And now you can start using your breakpoints and whatever you want. No browser extensions, no custom stacks. Just your own computer and your favorite browser.

If still it doesn’t work, in the Debugger configuration delete the “Before launch tasks”. Seems something broke in the new PHPStorm — you will have to run both manually, but still it will work.