Set Up PHP Debugging with Xdebug and Visual Studio Code

Tracking PHP errors is sometimes challenging when you only rely on browser messages, log files, or repeated var_dump() checks. A minor problem in the code can result in broken pages, failed form submissions, API errors, or other unpredictable behavior throughout your application.

That is where a proper PHP debugging setup helps. Tools such as Xdebug and Visual Studio Code allow you to pause your code execution, inspect variables, trace the execution process, and understand exactly where an issue starts.

In this guide, you’ll learn how to set up PHP debugging using Xdebug and Visual Studio Code. We’ll cover the basics of PHP debugging, how Xdebug works, what you need before setup, and how to configure it for the latest PHP development workflow.

What Is PHP Debugging?

PHP debugging is the task of detecting and resolving errors in PHP code. These could be syntax mistakes, wrong variable values, broken logic, invalid database queries, or unexpected actions in a web application.

Many developers start by checking PHP log files for errors or adding temporary statements, such as:

• echo: Outputs a value or message directly on the page.
• print_r(): Displays readable information about arrays or variables.
• var_dump(): Shows detailed information about a variable, including its type and value.

These techniques are useful for common problems, but they are limited when you need to trace a complex request, inspect numerous parameters, or figure out how individual components of the application interact.

A PHP debugger gives you more control. Instead of guessing where the problem is, you can pause the code at a certain line, go through it one step at a time, and check what is happening at each stage.

Debug PHP Using Error Logs

Before setting up Xdebug, it’s worth checking your PHP log files. These logs give you a quick view of warnings, notices, fatal errors, missing files, memory issues, and other problems that happen while your app is running.

They can be very helpful when a page shows a blank screen, a request fails without an obvious message, or an issue occurs on a live or staging server where you do not want error messages to be displayed in the web browser.

Enable PHP Error Logging Through Configuration

The simplest way to manage your PHP error logging is through the config file. Go ahead and open your php.ini file and make sure you have these in place:

log_errors = On
error_log = /path/to/php-error.log
display_errors = Off
error_reporting = E_ALL

Here is what each setting does:

• log_errors will put your PHP error data into a log file.
• error_log tells PHP where to write those errors.
• display_errors controls whether errors appear in the browser. For development, you may choose to display errors temporarily. In staging and production systems, keep it turned off and rely on the logs. This prevents sensitive server paths, configurations, or code data from appearing publicly.
• error_reporting defines which types of errors PHP should report. For most development environments, use E_ALL so that when you are debugging, you see every warning, notice, and deprecation message. If you get too many deprecation warning messages from legacy code, you can use E_ALL & ~E_DEPRECATED. For production, choose a less verbose setting such as E_ALL & ~E_NOTICE & ~E_DEPRECATED, which reports important errors and warnings but excludes notices and deprecations.

After you have made your changes to the configuration, don’t forget to restart the web server or the PHP-FPM service for the changes to take effect.

Enable PHP Error Logging in a Specific PHP File

Sometimes you just want to test one script. You can handle that by adding some code to the top of the PHP file in question:

<?php
error_reporting(E_ALL);
ini_set('log_errors', '1');
ini_set('display_errors', '0');
ini_set('error_log', __DIR__ . '/php-error.log');

This will have PHP report everything and put it in a php-error.log in the same folder without showing it in the browser.

But only do this with files you have control over, be it a custom plugin, a theme file, or a controller. It is for temporary testing; once you are done with your debugging, remove the code.

Enable PHP Error Logging Through .htaccess

If the server you have uses Apache and permits .htaccess overrides, you can configure error logging from the .htaccess file:

php_flag log_errors On
php_flag display_errors Off
php_value error_reporting E_ALL
php_value error_log /path/to/php-error.log

Bear in mind this won’t work in every hosting situation, particularly if the server doesn’t let you set PHP values in .htaccess or if you are running PHP via PHP-FPM.

View Cloudways Error Logs for PHP Debugging

If you are hosting your app on Cloudways, the logs can be viewed from the Cloudways platform instead of searching the server files.

Log in to your Cloudways account and find your app. Then go to Monitoring > Logs > Error Logs.

This screen displays recent application errors, including PHP warnings, fatal errors, failed scripts, file paths, and line numbers. These specifics make it possible to quickly detect problems with custom code, plugins, themes, DB connections, or config issues.

Cloudways shows the latest entries of logs on the platform. You can also SSH/SFTP into your server and look at the logs to investigate further.

Cloudways MCP adds another option for AI-assisted workflows by letting supported AI tools like Claude, Gemini, and ChatGPT connect with your Cloudways infrastructure. This can help you access hosting-related details, including logs, from your preferred AI tool.

How to Read a PHP Error Log

A typical PHP error log will show the type of error, message, complete path of the file affected, and line number where the issue occurred.

For example:

PHP Fatal error: Uncaught Error: Call to undefined function getUserData() in /home/app/public_html/index.php on line 24

This implies that:

• PHP stopped executing the script because it hit a fatal error.
• PHP tried to call a function that does not exist.
• The issue happened in index.php.
• The problem is on line 24.

Once you know the file and line number, open the file in an editor and look at the code near that line. In many cases, logs are enough to fix basic problems like variables that are not defined, wrong file paths, functions that do not exist, or syntax mistakes.

Why Use Xdebug for PHP Debugging?

Xdebug is one of the most widely used debugging extensions for PHP. It allows you to link a PHP application to an IDE or code editor (for example, Visual Studio Code) to debug the code in your development environment.

Xdebug offers the following:

• Set the breakpoints in PHP files.
• Step through one line at a time in the code.
• Examine objects, variables, arrays, and more.
• Track function invocations.
• Review the call stack.
• Debug CLI scripts and web requests.
• Run the code and check where it is slow.

Xdebug allows you to detect issues that are hard to catch through logs alone. For example, if a WordPress plugin, Laravel controller, or custom PHP function returns the wrong result, Xdebug lets you follow the request until you find the precise line responsible for the issue.

Prerequisites

Before setting up PHP debugging with Xdebug and Visual Studio Code, have the following ready:

• A working PHP environment.
• Access to your php.ini configuration file.
• Xdebug installed or permission to install it.
• Visual Studio Code installed on your system.
• The PHP Debug extension for Visual Studio Code.
• Access to restart PHP, Apache, NGINX, or PHP-FPM after configuration changes.

You should also confirm which PHP version your application is using. Run the following command in your terminal:

php -v

Then check whether Xdebug is already installed:

php -m | grep xdebug

If Xdebug is installed, you should see Xdebug in the output.

You can check the Loaded Configuration File with the following command:

php --ini

This helps you confirm which php.ini file PHP is using, so you do not update the wrong configuration file during setup.

Once these basics are ready, you can install and configure Xdebug for your operating system or server environment.

Install Xdebug

The installation process varies depending on your operating system and PHP environment.

Install Xdebug on Linux

On Ubuntu or Debian-based systems, Xdebug can be installed with the package manager:

sudo apt update
sudo apt install php-xdebug

For a specific PHP version, use the matching package name:

sudo apt install php8.3-xdebug

Install Xdebug on macOS

If you’re using PHP through Homebrew, install Xdebug with PECL:

pecl install xdebug

Install Xdebug on Windows

On Windows, the easiest method is to use the Xdebug installation wizard.

Create a file named phpinfo.php in your local web server directory and put the following code into it:

<?php
phpinfo();

Start your local web server and open that file in a browser, for example: http://localhost/phpinfo.php. The browser will display the full PHP configuration output. Copy that output and paste it into the Xdebug installation wizard.

The wizard will recommend the correct Xdebug DLL file for your architecture, PHP version, and compiler build. Download the recommended DLL file and place it inside your PHP ext directory.

Verify Xdebug Installation

Once you have installed Xdebug, head to the terminal and make sure it is being loaded by PHP with this:

php -v

If Xdebug is correctly installed, it will show up in the output.

To be sure which configuration file your CLI commands are pulling from, run:

php --ini

The Loaded Configuration File in the results will tell you what php.ini is in effect when you use the terminal.

Things can be a bit different for the web server or PHP-FPM when you are debugging a page in the browser. The easiest way to check is to put a quick phpinfo.php file in a folder the web can get to, like public_html:

<?php
phpinfo();

Browse to it at https://yourdomain.com/phpinfo.php and on the information page that comes up, find the Loaded Configuration File value. This is the php.ini used by the web server or PHP-FPM.

When you are done, don’t forget to remove that temporary phpinfo file.

Configure Xdebug 3

What you need to do next is put the Xdebug 3 settings in the PHP config file for the environment you are debugging. This applies if you are running it from the terminal or via a browser request.

Browser debugging is useful when the issue happens during a web request, such as loading a page, submitting a form, running a Laravel route or controller, debugging WordPress plugin or theme errors, or checking database errors triggered by a page request.

Terminal debugging is useful when the PHP code runs from the command line, such as standalone PHP scripts, Composer scripts, cron jobs, queue workers, Laravel Artisan commands, migrations, or seeders.

PHP can load different configuration files for browser requests and CLI commands, so check the right config file before enabling or troubleshooting Xdebug. If you are debugging PHP from the terminal, use the config file shown by php –ini. For a page being debugged in the browser, use the config file shown by phpinfo().

Once you have located the appropriate config file (php.ini), add these settings:

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

Update the path to where your PHP ext directory is located. For example:

zend_extension="C:\xampp\php\ext\php_xdebug.dll"

Here is what each setting does:

• zend_extension loads the Xdebug extension.
• xdebug.mode=debug enables step debugging.
• xdebug.start_with_request=yes starts a debugging session with each request.
• xdebug.client_host=127.0.0.1 tells Xdebug to connect to your local machine.
• xdebug.client_port=9003 is the port Xdebug 3 uses.

Save the file and restart the web server or PHP-FPM service.

After restarting the service, check that Xdebug is loaded:

php -v

You can also check the full Xdebug configuration with:

php -i | grep xdebug

If Xdebug appears in the output, your PHP environment is configured to debug in VS Code.

Set Up Visual Studio Code for PHP Debugging

After installing and configuring Xdebug, the next step is to connect it to Visual Studio Code.

You can install the PHP Debug extension via the command palette or the extensions panel.

1. Launch VS Code.

2. On Windows/Linux, press the keys Ctrl + Shift + P. On macOS, press the keys Cmd + Shift + P.

3. Search for Extensions: Install Extensions.

4. Search for PHP Debug and install it.

After you install it, open your PHP project, navigate to the Run and Debug panel, and create a new launch.json file.

When VS Code prompts you for a debug configuration, select PHP as the environment.

VS Code will create a .vscode/launch.json file inside your project. Then, add this config inside that launch.json file:

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

This is telling VS Code that it should listen on port 9003 for incoming Xdebug connections.

Test PHP Debugging in VS Code

To put your PHP debugging to the test, open up a PHP file and set a breakpoint by clicking beside a line number.

Take this bit of code, for instance:

<?php

$name = 'John Doe';
$message = 'Hello, ' . $name;

echo $message;

Put a breakpoint on the $message line.

Head over to the Run and Debug view and choose Listen for Xdebug.

Now start the debugger and execute your script from the terminal or browser using:

https://yourdomain.com/test-debug.php

As the script runs, VS Code should pause there, letting you step through the code and have a look at the variables.

Should the breakpoint be missed, make sure of a few things: Xdebug is shown in php -v, the port in launch.json is the same as in php.ini, and that you have updated the right php.ini file and restarted the web server or PHP-FPM service.

Also, confirm VS Code is actually listening for Xdebug. Once you have all that in order, your local setup with Xdebug and VS Code is good to go.

Use Xdebug Profiling to Find Performance Bottlenecks

While debugging is for errors, profiling is how you get to the bottom of performance. It will show you where an app is wasting time and which functions are taking too long during a request.

This is useful when a page is slow to load, a database operation drags on, or a certain feature adds unexpected overhead.

To enable profiling, change your Xdebug config to:

xdebug.mode=profile
xdebug.start_with_request=trigger
xdebug.output_dir=/tmp
xdebug.profiler_output_name=cachegrind.out.%p

This means Xdebug will only write a profile file when you trigger it. You can trigger profiling by adding this setting to the end of your URL:

?XDEBUG_TRIGGER=1

For example:

https://yourdomain.com/example-page.php?XDEBUG_TRIGGER=1

Once the request is done, the profiling file will be in the output directory. You can then open the profile file in Webgrind, KCachegrind, or QCachegrind to examine the function calls and execution times.

Do not run profiling on every request of a live site. It adds overhead and can produce large files. Only enable it to look into a specific performance problem.

Common Xdebug Setup Issues

Even after Xdebug is installed correctly, small mistakes in configuration can stop debugging from working. Here are the most common problems and how to fix them.

1. Xdebug is Missing From PHP

When you run php -v and Xdebug doesn’t show up, it means PHP has not picked up the extension. You can check which configuration file is active with:

php --ini

Make sure your Xdebug settings have been put into the php.ini that is listed as the Loaded Configuration File. After you have saved those changes, restart the web server or PHP-FPM.

2. Trouble With Port 9003

The default port for Xdebug 3 is 9003. If VS Code is set to something else, you need to make the two listen on the same port. Have a look at your php.ini and verify you have:

xdebug.client_port=9003

Do the same in the VS Code launch.json:

"port": 9003

If another process has the port tied up, pick a new one and update both the Xdebug and  VS Code settings accordingly.

3. VS Code Is Not Listening

Xdebug has no way to connect unless the debugger in VS Code is actively listening. So before you go to the browser and open the page, head over to the Run and Debug view in VS Code and start the right debug configuration. Leave it running as you make your test request.

4. Xdebug Works in CLI but Not in the Browser

This can happen because PHP is allowed to have separate config files for web requests and the command line. A quick way to check your CLI setup is with:

php --ini

Look at the output, and you will see the Loaded Configuration File value; that is your php.ini for the CLI.

To do the same for the browser, put a temporary phpinfo.php file in a folder the web can get to, like public_html, the root of a WordPress install, or Laravel’s public folder:

<?php
phpinfo();

View it in your browser and again note the Loaded Configuration File; that is what the web server is using.

There is no rule that says the two have to be the same. If you want to debug in the browser, put your Xdebug settings in the web server’s PHP config and give the web server or PHP-FPM a restart.

And remember to clean up and delete that phpinfo file when you are done, especially if you are on a public server.

5. Profiling Files Are Not Created

When profiling files fail to appear, look at the xdebug.output_dir setting. The directory has to be there, and the PHP process needs the right permissions to write to it.

Say you have xdebug.output_dir=/tmp set, you need to be sure PHP can actually put files in /tmp. If you are using a custom directory, create it first and set the proper permissions.

Recommended PHP Debugging Practices

Having a sound debugging workflow will let you zero in on problems more quickly, all while keeping your application from being slowed down or putting any sensitive data at risk.

• Make use of Xdebug for step-by-step visibilityWhile logs are fine for a quick look, they won’t tell you how a value is changing as the code runs. When you have to get to the bottom of why a condition returns a different result or want to see the request flow and function calls up close, Xdebug is the way to go.
• Don’t leave Xdebug running when you don’t need toXdebug puts overhead on your app, production in particular. If you aren’t actively profiling or debugging, leave it off. On a live system, turn it on for a brief session to do your investigation and then switch it back off once you have resolved the issue.
• Be sure to clear out test filesOnce you are done using them, get rid of any temporary scripts like phpinfo.php or test-debug.php. You don’t want to be handing over server details, paths, extensions, and PHP configuration to the public.
• Set your breakpoints with some thoughtPut breakpoints where you expect trouble to be – the controller, the form submission logic, a plugin function, or the relevant database query. Too many breakpoints only make it harder to follow. Pick a few key ones to start with and add more if you have to.
• Pair Xdebug with your logsYou can get a better picture by using the two together. Xdebug will show you what is happening in real time, but logs are there to review errors after a request completes. Inspect the request with Xdebug and then check the error log to verify any fatal errors, failures, or warnings from the server.
• Verify the environmentA bug might not show up everywhere due to a difference in cache, file paths, the PHP version, or even the database. Make sure you know if this is a local, staging, or production problem, and do your debugging in the one where you can safely reproduce it.

Final Thoughts

Manual checks are a thing of the past when you have the right tools for PHP debugging.
Pair Xdebug with VS Code, and you have a practical means of halting code, looking at variables, and tracing execution to see where an issue originates.

For local development, a simple Xdebug setup in VS Code is often enough. Should performance be an issue, let Xdebug’s profiling point out any expensive requests or slow functions.

Use Xdebug carefully; Keep it enabled only when needed, and get rid of any temporary files once testing is over. A tidy setup means you can debug PHP apps faster and track down the root cause of a problem with more confidence.

Nisha Thomas

Nisha is a technical content writer with a passion for translating complex technology into content that’s clear, practical, and enjoyable to read. With strong technical insight and a user-first mindset, she crafts guides that help readers understand and use modern tools and platforms.

Get Connected on: Twitter Community Forum