Debugging PHP with Xdebug

Welcome dear reader, today you will learn how to debug PHP applications with Xdebug. If you have ever littered your code with var_dump() calls to find a bug, you know the pain. A real debugger lets you pause your application at any line, inspect every variable, and step through the code line by line — like a freeze-frame for bugs.

Table of contents

• What is Xdebug and How Does It Work?
• How to Install Xdebug
• How to Configure Xdebug
• How to Set Breakpoints in Your Editor
• Conclusion

What is Xdebug and How Does It Work?

Xdebug is a PHP extension that connects your running PHP application to your editor over a protocol called DBGp. When you set a breakpoint, the application pauses execution at that line and sends the current state — variables, call stack, everything — to your editor, which then displays it in a friendly interface.

The magic ingredient is xdebug.mode. In debug mode, Xdebug waits for your editor to connect before stepping through code. There is also a develop mode that improves error messages, and a profile mode that records how long each function takes — useful once you hunt performance instead of bugs.

How to Install Xdebug

On Ubuntu or Debian, Xdebug is available from the package manager:

# Install Xdebug for PHP
sudo apt install php-xdebug

# Verify that the extension is loaded
php -m | grep xdebug

If you use Docker for local development, add the extension to your image instead:

# Install Xdebug in a Docker PHP image
RUN pecl install xdebug && docker-php-ext-enable xdebug

How to Configure Xdebug

Create a configuration file — on Ubuntu, for example /etc/php/8.2/mods-available/xdebug.ini — with the following settings:

# Load the extension
zend_extension=xdebug

# Enable the debugger
xdebug.mode=debug

# Where your editor listens for connections
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

Then restart your PHP service or web server, for example with sudo systemctl restart php8.2-fpm. If your application runs in a Docker container, like we covered here, remember the container’s 127.0.0.1 is not your host machine — set xdebug.client_host=host.docker.internal instead.

How to Set Breakpoints in Your Editor

In VS Code, install the PHP Debug extension, then add a configuration to .vscode/launch.json:

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

Start the debugger with F5, open the file you want to inspect, and click the gutter next to a line number to set a breakpoint — a red dot. Now trigger that code path in your browser, and the application freezes exactly there: hover any variable to inspect its value, use F10 to step over lines, and F11 to step into functions.

Conclusion

That’s already it to start debugging PHP with Xdebug. Install the extension, enable debug mode, point your editor at port 9003, and set your first breakpoint. Say goodbye to scattered var_dump() calls — your future self will thank you. Leave a comment below if you have any questions or feedback about the content of this article.

At re:Software S.L., we create innovative solutions for businesses that aim to digitize their processes and routines, and are always available to help our customers and development teams debug source code!