How to debug Laravel with XDebuger in VS Code

To be able to debug Laravel applications during development will give you a huge advantage, compared to your colleagues who are struggling their way through using echo or print_r statements. The ability to pause the execution is often crucial to understand how the code works and where the bug is.

Following steps are required:

1. Install XDebug
2. Install xdebug.php-debug for VS Code released by XDebug
3. create a launch.json file

The first and the second step can sometimes be relatively tricky to get right, however I am confident if you follow my instructions you will get it to work.

Install XDebug

(If you have it already installed and are just here, because the other tutorial didn't work, then I have a tip for you. Look at the configs I am providing, which will enable a different the XDebug log level. This often helps to figure out why it is not working.)

I would recommend that you head over to https://xdebug.org/docs/install and look at one of their installation guides, because it will be different for most people. If you use a Unix based system like macOS or Linux you are in luck and the installation will be easier, because you most likely can install it with PECL or Homebrew If this is not possible, simply download the zipped file and follow the instructions on their wizard page. https://xdebug.org/wizard

The same goes for Windows user. On Windows you might even first update your PHP Version since not all versions are compatible.

Take a way - the installation of XDebug will be different for most OS and PHP versions, hence it is almost impossible to give a general how to guide.

1. Check the main page and see if you can install it using CLI tools https://xdebug.org/docs/install
2. If you cannot install it with a CLI tool, head over to the wizard and past the output from php -i https://xdebug.org/wizard
3. Check that XDebug is properly installed - you can do that using php -i and search the output for debug. If it is installed, it should be listed under extensions. (you might need to enable it putting zend_extension = xdebug into your php.ini file)
4. After successful installation adjust the XDebug.config file. (The file will be named differently depending on your OS. The wizard should have told you how it was named.)

To get the configs right can sometimes be quite difficult. However, the installation is actually the hardest part. Once you know where you can set the settings for XDebug it gets actually simpler.

Below, you can see possible configs for XDebug. I added comments to each line, so you actually understand what it does. Often you will see that the boolean fields are being set with either on, 1, yes - again different version need different values. However, for me, it was never an issue and could actually use these settings interchangeable.

zend_extension = xdebug

xdebug.remote_enable=on ; enables the extension
xdebug.remote_autostart = 1 ; required to be true so xdebug is started for ever php process 
xdebug.start_with_request=yes ; so it turns on for every http request

xdebug.log=/tmp/xdebug.log ; the logging - turn of once evrything works


xdebug.mode=develop,gcstats,coverage,profile,debug ; just give it the modes you need it can take all of them
xdebug.idekey=VSCODE ; can also be phpstorm

xdebug.client_port=9003 ; the port xdebig will be working on

The logging actually helped me a lot to set it up correctly, especially in docker container. I will soon release a guide for my favorite dev environment for Laravel. If you want to read more about the different modes, have a look here https://xdebug.org/docs/upgrade_guide

xdebug.log=/tmp/xdebug.log 

Okay now, when you start your Laravel application with php artisan serve you should see an output where XDebug is complaining that it cannot connect. This will be solved in the next section.

Set Up VS Code

First install xdebug.php-debug for VS Code released by XDebug plugin for VS Code. Once done, find the debugger view.

Inside the Debugger view you can now create a launch.json file, this will bring down a dropdown in which you simply choose PHP. VsCode will now create a launch.json into the .vscode folder. In there you will find several configs. We are actually only interested into the first config. Here, it is crucial that the port is the same as the port in the XDebug config file.

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003
}

Once the port is the same you should be able to hit the play button in the debugger view, make sure you have selected the correct launch configs. Now you should be able to set break points.

I know I did not give you guys an exact step-by-step guide on how to install XDebug, but this is because it is so different for most people. If many of you struggle with it, I can make a video where I show how I install it. For Windows users, it might even be easier to have a look at my upcoming article where I show a great set up where everything is normalized through docker.