minutes read

A better way to debug your PHP code

Khoa Pham

November 16, 2022

feature image


Debugging is equally as important as coding, like how carefully you write your code, you should treat debugging the same. Now we all know some easy debugging functions such as error_log and var_dump, but this article will introduce you to a more convenient and effective approach to debugging PHP code.

Enter Xdebug - a PHP extension that provides debugging and profiling capabilities, using DBGp debugging protocol.

Why Xdebug?

With Xdebug, you no longer need to litter your code with error_log, print_r(), or var_dump()! That may sound cool already, but what even cooler is that Xdebug can also:

  • Display information on all variables, not just the one you passed
  • Allow you to change the values of one or more variables on the fly while maintaining the execution of your application
  • Support various IDE for PHP projects

All in all, Xdebug saves you a bunch of time and also gives you a more comprehensive code review.

How to install Xdebug

Prerequisite: PHP has been accurately installed

On macOS

Here is how you can install Xdebug through PECL on macOS with Homebrew.

Prerequisite: Xcode's command line tools (run: xcode-select --install).
You should ignore any prompts to add "extension=xdebug.so" to php.ini — this will cause problems.

On Windows

To install Xdebug on Windows, download the package from https://xdebug.org/download.Then browse to this page and follow its instruction: https://xdebug.org/wizard

On Ubuntu

Depending on your distribution, run one of the following commands:

Linux distributions might be providing an old and/or outdated version. If the package manager installs a version that is no longer supported (see Supported Versions), please install Xdebug with PECL, or from source instead.

On Docker

Our teams at FABA often use Docker for our new projects. To install Xdebug on Docker, please clone this repository and follow the README file.

How to configure Xdebug

Configure Xdebug in VSCode

There is a popular VSCode extension for PHP called PHP Debug. You can find it in the extension window and install it.

PHP Debug - a VSCode extension for PHP

After installation, reload the VSCode window. Now click on the debug console tab and click on Add Configuration.

Add Configuration in VSCode for PHP Debug

Now, select PHP as the environment. VSCode will now add a launch.json file in the root directory.

Finally, add the runtimeExecutable property to the list after port:

adding runtimeExecutable property

You will now see a few items in the window, through which you can select which logs Xdebugger will show, such as Notices, Warnings, Errors, and Exceptions.

As you navigate to the Debug Console section, you can see the details of errors and the debug execution buttons on top.

At this point, you can add breakpoints on the lines of code that you need to debug. Note that Xdebug will add the PHP debug script name with the line number on the bottom left section:

navigate to the Debug Console section to see the details of errors and the debug execution buttons

You can run the application in the browser, and then read the code line by line to see the errors and debug them properly.

Here are some shortcut function keys to quickly move through functions and lines of codes:
F5:  Continue Debugging
F10: Step Over
F11: Step into
Shift + F11: Step out

Configure Xdebug in PHPStorm

Since PHPStorm already supports Xdebug, you only need to do some minor configs:

configure Xdebug in PHPStorm

You can run the application in the browser, and then read the code line by line to see the errors and debug them properly.

Here are some shortcut functions keys:
F7: Step Into
F8: Step Over
F9: Continue Debugging
navigate through Xdebug in PHPStorm


Debugging is an important aspect of coding; without it, you can not tell what went wrong with your code.
This article has introduced Xdebug and demonstrated how to install/debug with Xdebug and configure it in VSCode and PHPStorm. You can also integrate it into other IDEs.

The best practice is to set up your debugging environment before writing the code. If you are working on a complex application containing thousands of code lines, you will need a PHP debugger to find errors and warning signs better.


  1. https://xdebug.org/docs/install
  2. https://xdebug.org/download
  3. https://medium.com/codex/8-best-ide-software-to-consider-in-2022-99478e34d4a4