PHPControls

Posted on Mar 9

Debugging PHP with VSCode and XDebug: A Step-by-Step Guide

#php #vscode #querro #xdebug

Debugging is an essential part of PHP development, and using Visual Studio Code with XDebug can greatly enhance your workflow. This guide will walk you through setting up XDebug, enabling breakpoints, stepping through code, using stack traces, and troubleshooting common issues.

1. Installing XDebug

Before you can debug PHP with VSCode, you need to ensure that XDebug is installed on your system.

Check if XDebug is Installed

From a phpinfo page, and check wether XDebug section and it is enabled.

Install XDebug If It's Not Yet Installed

If XDebug is missing, you can install it using pecl:

pecl install xdebug

After installation, add this line to your php.ini file:

zend_extension=xdebug

Remember to restart your web server or PHP service:

sudo systemctl restart apache2  # For Apache
sudo systemctl restart php-fpm  # For PHP-FPM

Now we need to configure XDebug to connect to VSCode

2. Configuring XDebug for VSCode

Edit your php.ini file and add the following configuration:

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/var/log/xdebug.log

Important:

Ensure your PHP service is restarted for any changes made in php.ini to take effect.

3. Setting Up VSCode for XDebug

1. Install the PHP Debug Extension

Open VSCode.
Go to Extensions (Ctrl+Shift+X).
Search for PHP Debug by Felix Becker and install it.

2. Configure VSCode Debugger

Open your project in VSCode.
Go to the Run and Debug panel (Ctrl+Shift+D).
Click on create a launch.json file. It should create default configuration as the following with port 9003. It is absolutely critical to have the same port as what is in xdebug.client_port in php.ini in previous step.

{
   "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003
        }
    ]
}

3. Start the Debugger

Click the green Start Debugging button or press F5.
Ensure XDebug is running and listening on port 9003. It actually can be any port number as 9003 is default.

The debugger bar should now appear right below tabs in VSCode.

4. Debugging Features

Setting Breakpoints

Open any PHP file.
Click in the left margin next to a line number or press F9 to set a breakpoint.
Run the debugger (F5) and execute the PHP script in your browser.
The script execution will pause at the breakpoint.

Stepping Through Code

While debugging, you can control execution using:

Step Over (F10) -- Move to the next line of code.
Step Into (F11) -- Enter into function calls.
Step Out (Shift+F11) -- Exit the current function.
Continue (F5) -- Resume execution until the next breakpoint.

Learn to Use Stack Trace

The Call Stack panel in VSCode shows the sequence of function calls leading up to the breakpoint.
Helps trace errors in deeply nested functions.
Click on any function in the stack to inspect its execution.

5. Troubleshooting Common Issues

Issue 1: Debugger Not Stopping at Breakpoints

Ensure XDebug is installed and configured correctly in phpinfo (See step 1)
Make sure the matching port (e.g. 9003) is set in both php.ini and launch.json.
Always restart Apache or PHP-FPM after making changes.

Issue 2: XDebug Not Connecting to VSCode

Verify the logs in /var/log/xdebug.log for connection issues.
Ensure VSCode is listening for XDebug (F5 in debug mode).
Disable other applications using port 9003 (like another debugger).

Issue 3: Path Mapping Problems

Ensure pathMappings in launch.json correctly maps the server path to the local workspace
Add $_SERVER['DOCUMENT_ROOT'] in your script to verify paths.

Conclusion

VSCode and XDebug together make debugging PHP a seamless experience. By following this guide, you should be able to install and configure XDebug properly, and set breakpoints and step through code, and also troubleshoot common debugging issues.

Finally, if manually tinkering isn't your thing, you can opt for a hassle-free solution like MAMP or XAMMP.

Happy debugging! 🚀

About the Author

The author is a full-stack web developer who created SQL-based data analytics and BI reports tool — Querro at querro.io

DEV Community