PHP Debugging with Xdebug in VSCode

Debugging is a critical part of software development. Yet many PHP developers still rely on var_dump() and echo debugging, even though modern tools provide much more powerful and efficient techniques. One of the best debugging tools available for PHP is Xdebug, especially when combined with Visual Studio Code.

Xdebug gives developers the power to inspect variables, pause execution, step through code, monitor call stacks, and even profile performance. When configured correctly, it significantly improves productivity and code quality.

In this guide, we’ll explore how to set up and use Xdebug in VSCode to streamline your debugging workflow.

Why Use Xdebug for PHP Debugging?

Before jumping into setup, let’s highlight why Xdebug is worth using:

With Xdebug, debugging becomes predictable, structured, and efficient, unlike trial-and-error print debugging.

Prerequisites

Before you start, ensure you have:

• PHP 7.4+ or PHP 8.x

• VSCode Installed

• A PHP project (local or server)

• Ability to modify PHP configuration (php.ini)

Step 1: Install Xdebug

Many systems already include Xdebug, but if not, it can be installed easily.

Check if Xdebug is installed:

Run:

php -v

If you see "with Xdebug" in the output, you're good.

Copy your phpinfo() output into the wizard, and it will tell you what to download and where to place it.

Step 2: Enable Xdebug in php.ini

Open your php.ini file and add or verify the following line:

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=127.0.0.1

Why port 9003?

Xdebug 3 uses port 9003 as default (not 9000 like older versions).

Restart the web server or PHP-FPM after making changes:

sudo service apache2 restart

or

sudo service php8.1-fpm restart

Step 3: Install PHP Debug Extension in VSCode

Open VSCode → Extensions → Search for:

PHP Debug

Install the extension authored by xdebug.org contributors.

Step 4: Configure Debug Settings in VSCode

Open the Debug panel → Click "Run & Debug" → Choose PHP → This creates a launch.json file inside .vscode folder.

The config should look like:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003
    }
  ]
}

This tells VSCode to listen for incoming debug connections.

Step 5: Start Debugging

1. Open a PHP file.

2. Click next to the line number to set a breakpoint.

3. Go to Run → Start Debugging (or press F5).

4. Visit your PHP page in the browser.

If everything is configured correctly:

The code execution will pause at your breakpoint, and VSCode will show:

• Local variables

• Global variables

• Call stack

• Watch expressions

Step 6: Useful Debugging Techniques

Stepping Through Code

• Step Over → Move to next line

• Step Into → Enter function call

• Step Out → Exit current function

Watch Variables

Add variables to the Watch panel to track values over time.

Inspect Call Stack

This shows how execution reached the current line—very useful for debugging complex logic.

Step 7: Profiling with Xdebug (Optional but Powerful)

Performance profiling reveals slow functions and bottlenecks.

In php.ini add:

xdebug.mode=debug,profile
xdebug.output_dir="/tmp/xdebug"

Use tools like Webgrind or qcachegrind to visualize profiling results.

Common Issues & Fixes

Best Practices for Debugging PHP with Xdebug

• Use conditional breakpoints to stop only when values match expected conditions.

• Keep Watch expressions for variables you frequently monitor.

• Combine debugging with unit tests for stable and predictable outcomes.

• For microservices, ensure remote debugging hosts are configured correctly.

Conclusion

Debugging with Xdebug in VSCode is one of the most effective ways to build reliable, maintainable PHP applications. By replacing manual debugging with breakpoints, stack traces, and profiling, you gain a deeper understanding of your system and reduce development time.

Once configured, it becomes second nature—and you’ll wonder how you ever coded without it.