Debugging a PHP project on VSCode with Xdebug

Have you ever faced a piece of code written in PHP that doesn't work as it should? If you don't have much experience debugging applications, surely you would have used error_log() and var_dump() a lot to inspect your variables, which works, but it could be better.

Having worked previously with other languages like C# or Java, I've learned to use breakpoints to inspect my code, and that is possible too in PHP thanks to Xdebug.

Xdebug is a PHP extension that gives the capabilities to debug and profile of our code, allowing us to inspect variables and check calls step-by-step. Under the hood, this extension uses the DBGp protocol that provides communication between the runtime engine (officially Zend Engine) and the IDE.

For this article, I assume you have already installed Visual Studio Code and the PHP runtime.

Installation on Linux & Mac

Life is easy for you: just run the following command and you are done. Remember to say "no" if it asks about adding the extension to your php.ini since we'll be reviewing that later.

# pecl install xdebug

Installation on Windows

Due to Windows' tendency to make stuff more complicated, installing Xdebug will require many steps.

Note: Since we'll be modifying just the php.ini file, it doesn't matter if you are using Apache, Nginx, Xampp, etc.

The first step is to identify your current version of PHP, for which you can create a new PHP file, put a phpinfo(), and then search for the following lines (use Ctrl+F).

• Version: Right at the start of the info page.
• Compiler: Take note of the compiler version (VC11, VC14, etc.)
• Architecture: It will tell you if you are using x86 (32 bits) or x64 (64 bits).
• Thread Safety: check if you have it enabled or not. If it is enabled, then your version is "Thread Safe" (TS), otherwise, it's "Non-Thread Safe" (NTS). More info here.

Having this info, you should go to the download page for Xdebug and choose the right version for your current setup. The DLL you'll get must be put in your PHP extensions folder, i.e. C:\xampp\php\ext.

Registering Xdebug on PHP

After Xdebug is downloaded and installed, you'll have to register and enable the extension in your php.ini. For this, open the file and at the end add the following lines:

[xdebug]
; Path for the library in the extensions folder
zend_extension="/path/to/xdebug"

; Enable communications using DBGp protocol
xdebug.remote_enable=1

; Automatically start a debugging session?
xdebug.remote_autostart=1

; Host on which the IDE will run. Useful when using Docker
xdebug.remote_host=127.0.0.1

; The port to use for DBGp. Default is 9000
xdebug.remote_port=9000

; Show stacktraces?
xdebug.default_enable=1

Edit: added more configuration options

💡 Remember to restart your web server after applying these changes.

Installing the VSCode extension

Now that the runtime engine is sending debug info through port 9000, we'll install the VSCode extension that allows us to communicate with the debugger from the IDE. For this guide, we'll be using "PHP Debug" by Felix Becker from the extensions marketplace.

The process is straightforward: install it, enable it, and done.

Configuring our project

Now that the debugger and the IDE extension are in place, you'll have to add the configuration to tell VSCode which tool will be used for debugging. To do this, follow these steps:

1. On the left side menu go to "Run".
2. At the top of the sidebar, if it says "No configurations", open the dropdown and choose "Add configuration".
3. In the "Select environment" prompt, choose "PHP".
4. Adjust the parameters according to the way you configured Xdebug in php.ini.

Start debugging

To add breakpoints, just click in the blank space to the left of the line numbers in the editor pane. A red dot will appear. After that, click the green play button in the sidebar; Now the bottom bar should change from blue to orange, signaling that it started in debug mode.

If you execute your code, the runtime will stop at the breakpoint and the IDE will allow you to inspect the variables at that moment in time, or use the step buttons to see what happens after that breakpoint. To continue executing your code, just press the play button again, or stop with the stop button (red square).

Final words

This was a very light approach to installing Xdebug and start debugging. I invite you to continue reading about remote debugging in the official documentation.

Happy coding!

Comments

[Senthur]

Hi mate,
'x' is missed in # pecl install debug. The correct way is # pecl install xdebug

[Manitra Andriamitondra]

Same here, at least on MacOS Catalina

[José González]

Sorry for the typo! Thanks for making the call :)

[dgloriaweb]

Hi, not working in Laravel 8. (XAMPP, VSCode, PHP 7.4.11, Zend Engine v3.4.0, Copyright (c) Zend Technologies
with Xdebug v3.0.2, Copyright (c) 2002-2021, by Derick Rethans )