This website uses cookies

Our website, platform and/or any sub domains use cookies to understand how you use our services, and to improve both your experience and our marketing relevance.

📣 Introducing DigitalOceans General Purpose & CPU Optimized Servers on Cloudways Flexible. Learn More

How to Set Up PHP Debugging Using Xdebug and VSCode

Updated on March 13, 2025

9 Min Read
debug-php

Key Takeaways:

  • PHP debugging involves enabling error logs, using tools like Xdebug, and adopting practices like debug-driven development.
  • Xdebug provides advanced debugging features such as breakpoints, stack traces, and profiling, and can be integrated with IDEs like VSCode.
  • Effective debugging is crucial for identifying and resolving code issues, leading to more robust and reliable PHP applications.

You must pay attention to a few things when developing web applications to deliver a smooth end product. Good developers follow the development best practices, including testing, debugging, etc., while creating robust apps.

This article discusses the PHP debug concepts and coding techniques. So read on to learn more about debugging PHP.

You can start debugging without any configuration. But, this is only suggested when you need to connect to an existing Web Server with Xdebug configured or want to run and debug a PHP script rapidly.

Let’s start with the basic level, where you tend to write PHP code using print_r(), var_dump() commands to debug the output of the written code. We have many PHP debugging tools, that let user urges to fix the errors during coding, and some functions that show you the correct output or errors/warnings in case of code failure. Although this PHP debugging technique is basic, it is still in use.

Stop Wasting Time on Servers

Cloudways handle server management for you so you can focus on creating great apps and keeping your clients happy.

What Are PHP Error Logs?

PHP error logs are very helpful instruments for developers in identifying and addressing problems within their applications. PHP error logs show total information concerning errors, notices, and warnings at script running time, e.g., error type, on which file the error has appeared, and real line number where the error had occurred. These logs enable developers to identify faults in real-time and implement fix measures by studying them.

Why are PHP Error Logs Important?

  • Debugging: Error logs assist you in determining syntax errors, runtime errors, and logic errors in your code.
  • Performance Monitoring: They may identify performance bottlenecks or inefficient code spots.
  • Security: Logs can inform you about potential vulnerabilities or attempts to access through unauthorized means.
  • Production Safety: In production, error logs help you track issues without revealing sensitive information to users.

PHP Error Logging Configuration

To enable and set up PHP error logging, you must change settings in your php.ini file or use runtime directives such as ini_set().

I. php.ini Main Directives:

These are the primary directives for error logging:

  • log_errors: Turn error logging on or off.
log_errors = On
  • error_log: This is where errors will be logged. Use an absolute path so that it is obvious.
error_log = /var/log/php_errors.log
  • error_reporting: These specify what kind of errors are to be logged. For instance:
error_reporting = E_ALL
  • E_ALL: Logs all the errors, warnings, and notices.
  • E_ERROR | E_WARNING: Logs fatal errors and warnings.

II. Logging by.htaccess (Per Directory):

If php.ini is not accessible or modifiable due to limited access issues, you can log per directory through.htaccess. You can add the following code block in your concern application .htaccess file:

php_flag log_errors On
php_value error_log /path/to/php_errors.log

III. Runtime Configuration using ini_set():

You can also enable logging dynamically within your PHP scripts by adding the following code block:

ini_set('log_errors', 'On');
ini_set('error_log', '/path/to/php_errors.log');

Viewing PHP Error Logs

PHP error logs are saved differently depending on the hosting configuration:

  1. Default Locations:
  • For Linux servers: /var/log/php_errors.log or /var/log/syslog
  • For Windows servers: Event Viewer (in case error_log is configured as syslog)

b. Cloudways-Specific Instructions:

For Cloudways-managed servers, you can easily follow the steps to view your logs without putting any extra effort.

  • Login to your Cloudways dashboard.
  • Go to Server Management > Monitoring > Logs.
  • Go to the “Application Logs” or “Server Logs” section to check PHP errors.

PHP Error Log Reading

PHP error logs give you an informative entry describing what occurred. Here’s an example log entry:

[13-Mar-2025 12:00:00 UTC] PHP Fatal error: Uncaught Exception: Database connection failed in /var/www/html/index.php on line 25

Log Breakdown:

  • Timestamp: [13-Mar-2025 12:00:00 UTC]
  • Error Type: PHP Fatal error
  • Message: Uncaught Exception: Database connection failed
  • File & Line Number: /var/www/html/index.php on line 25

With such log entries, you can backtrace errors to their source and correct them appropriately.

PHP Error Log Best Practices

You will need to differentiate Development and Production settings as follows.

In development setup, you may include the following:

display_errors = On
log_errors = On
error_reporting = E_ALL

In production setup, you may include the following:

display_errors = Off
log_errors = On
error_reporting = E_ALL & ~E_NOTICE & ~E_DEPRECATED & ~E_STRICT
  • Rotate Log Files: Avoid log files from becoming too large by utilizing log rotation tools such as logrotate.
  • Secure Log Files: Limit log file access via file permissions (e.g., chmod 600 /path/to/php_errors.log) so that it is not possible for unauthorized access.
  • Monitor Logs Regularly: Utilize monitoring software such as Rollbar or Loggly for real-time log analysis.
  • Framework-Specific Logging (e.g., Laravel): If you are working with a framework such as Laravel or Symfony, use their built-in logging for tighter integration and more flexibility.

What is PHP Debug Driven Development?

Earlier, I was unsure of the debug-driven development (DDD) term, but I got this idea from a debugger friend. His code contained multiple breakpoints, and he went through each line response till he got the desired output.
Don’t be confused with breakpoints, as I will demonstrate them. DDD has a similar flow to TDD, where you first define all the PHP debugging techniques for configuration and then write the code to debug if any errors arise.
Once you have an idea of DDD, you should learn about Xdebug, which helps you understand the concept of PHP debug-driven development. Running PHP with Xdebug gives you full insights into errors, responses, and code coverage.

What Is Xdebug?

Imagine you’ve written your code, and the code breaks just when you compile it. And the worst part is that you can’t identify what went wrong. Xdebug is your savior here.

Xdebug is a PHP extension that helps developers debug and smoothen the development of their projects to watch for errors and resolve them. It upgrades PHP’s var_dump() function and adds stack traces for notices, warnings, errors, and exceptions.

Xdebug uses the DBGp debugging protocol and gives debugging and profiling capabilities. It allows us to add breakpoints and stop the code execution at every breakpoint to see variables output in only one code iteration.

So Xdebug lets you save your time, which is otherwise lost in code debugging. Without Xdebug, you must refresh the page to see the output again. You can also set breakpoints independent methods to see which one is causing issues.

Also, you can add as many breakpoints as you want in the code and use a PHP debugger to check each code line by line.

Install Xdebug in PHP

Now it’s time to install Xdebug in PHP. There are a few options through which you can install Xdebug.

Windows:

For windows users, Xdebug is providing a wizard tool through which you can download the related .dll file. For this, first, create a PHP file in folder, and add the following line of code:

<?php

phpinfo();

?>

Run the file in the browser. You will see the PHP information. Copy the details and put them in the wizard tool and click on Analyze my phpinfo() output button.

php xdebug

This will give you the following output:

php xdebug

Now, download the .dll files and follow the above-mentioned instructions to put files in the xampp/php/ext directory. Next, follow step 3 to enable Xdebug in the php.ini file, and finally restart the webserver.

MAC

You can install PHP7 Xdebug using pecl extension:

pecl install xdebug

Linux

On Linux distribution like Debian, you can use Sudo to install Xdebug in PHP:

sudo apt install php-xdebug;

Now, open the file etc/php/7.0/mods-available/xdebug.ini and add the following code to enable Xdebug:

xdebug.profiler_enable_trigger = 1

xdebug.profiler_enable = 0

xdebug.remote_enable = 1

xdebug.profiler_output_dir = "/tmp"

Now, restart the Apache2 server.

sudo service apache2 restart;

GIT

You can also clone it from GitHub.

git clone git://github.com/xdebug/xdebug.git

After installing Xdebug, open the php.ini file, and enable the extension.

zend_extension="xdebug.so"

Now, check the PHP version using the command `php -v`. You will see the Xdebug version installed with PHP.

$ php -v

PHP 7.2.0RC6 (cli) (built: Nov 23 2017 10:30:56) ( NTS DEBUG )

Copyright (c) 1997-2017 The PHP Group

Zend Engine v3.2.0-dev, Copyright (c) 1998-2017 Zend Technologies

 with Xdebug v2.6.0-dev, Copyright (c) 2002-2017, by Derick Rethans

Configure Xdebug in VSCode

If you want a smooth workflow with Xdebug, you can integrate it into your favorite IDE like phpstorm, Zend studio, and VScode. Let’s configure Xdebug in Visual Studio Code to debug PHP.

Improve Your PHP App Speed by 300%

Cloudways offers you dedicated servers with SSD storage, custom performance, an optimized stack, and more for 300% faster load times.

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

php debug extension

After installation, you must reload the VSCode window. Now, again run phpinfo(); method in any PHP file to check if Xdebug is enabled or not.

Now click on the debug console tab and click on add configuration.

add configuration

Now, you must select the environment which is PHP. VSCode will now add a launch.json file in the root directory.

launch file

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

"runtimeExecutable": "C:\\xampp\\php\\php.exe"

Save the launch.json file. Open the debug mode tab, and click on the green debug button to start the debugging option.

php debugging

You will now see few items in the window, through which you can select what logs Xdebugger will show like:

  • Notices
  • Warnings
  • Errors
  • Exceptions
  • Everything

Navigate to the Debug Console section which shows you 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:

php debug script

You can run the application in the browser, and then read the code line by line, to see the errors and debug them properly. Also, you need to remind a few shortcut functions keys to move through functions and line of codes:

F5:  Continue Debugging

F10: Step Over

F11: Step into

Shift + F11: Step out

php debug options

Xdebug Profiling

Xdebug also provides profiling of code just like other profiling tools, Blackfire and Tideways. If you want to use the profiling option, then you must enable it in the php.ini file.

xdebug.profiler_enable=1

xdebug.profiler_output_dir="C:\xampp\tmp"

Now, open a file and start entering all the profiling logs.

Revolutionize Your Website Experience. Join Cloudways today!

Step into the future of hosting with Cloudways Managed hosting. Experience seamless scalability, unmatched speed, and ironclad security.

Final Words

Debugging is an important aspect of coding; without it, you can’t tell what went wrong with your code.

This article has demonstrated how to enable PHP to debug with Xdebug and configure it in VSCode. You can also integrate it in Eclipse, PHPstorm, and other IDEs.

For those venturing into the realm of extensive coding, setting up a robust debugging environment is paramount. Especially when tackling intricate applications spanning thousands of lines, having a PHP debugger in place becomes essential to unearth errors and warning signs. With the assistance of advanced tools and the reliability of PHP web hosting, you’re equipped to navigate the complexities of coding and ensure a seamless development experience.

If there is anything you want to know more about, post your queries and suggestions in the comments section below.

Q. How do I debug in PHP?

A. To debug in PHP, you can use tools like Xdebug, which allows you to set breakpoints, inspect variables, and step through code. Basic debugging can be done using var_dump(), print_r(), or error_log(). For more structured debugging, enable PHP error logging and use debugging features in IDEs like Visual Studio Code or PhpStorm.

Q. How to enable PHP debug mode?

A. To enable debug mode, modify the php.ini file by setting:

display_errors = On
error_reporting = E_ALL

For production environments, log errors instead of displaying them:

log_errors = On
error_log = /path/to/logfile.log

Q. Is PHP easy to debug?

A. Yes, PHP is easy to debug using built-in functions like var_dump(), echo, and print_r(). For more advanced debugging, tools like Xdebug allow step debugging, breakpoints, and stack traces, making it easier to identify issues.

Q. How to add debugging to PHP?

A. You can add debugging to PHP using:

  • Error Reporting: Enable error reporting in your script:
error_reporting(E_ALL);
ini_set('display_errors', 1);
  • Logging: Configure PHP to log errors in php.ini or use error_log('Error message');
  • Xdebug: Install and configure Xdebug for advanced debugging.
  • Debugging Functions: Use var_dump(), print_r(), or debug_backtrace() to inspect variables and execution flow.

Q. How to debug PHP with Xdebug and VSCode?

A. To debug PHP with Xdebug in VSCode:

  1. Install Xdebug and configure php.ini:
    xdebug.mode=debug
    xdebug.start_with_request=yes
    xdebug.client_host=127.0.0.1
    xdebug.client_port=9003
  2. Install the PHP Debug extension in VSCode.
  3. Add a launch.json configuration file in VSCode.
  4. Set breakpoints in your PHP code and start debugging.

Q. How to configure Xdebug in PHP?

A. To configure Xdebug, install it and modify your php.ini file with:

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

Restart the web server for changes to take effect.

Q. How to set PHP debug executable path in VSCode?

A. To set the PHP executable path in VSCode, open Settings and search for php.executablePath, then provide the full path to your PHP installation, e.g.,

"php.executablePath": "C:/xampp/php/php.exe"

Share your opinion in the comment section. COMMENT NOW

Share This Article

Salwa Mujtaba

Salwa Mujtaba is a Technical Content Writer at Cloudways. With a strong background in Computer Science and prior experience as a team lead in Cloudways Operations, she brings a deep understanding of the Cloudways Platform to her writing. Salwa creates content that simplifies complex concepts, making them accessible and engaging for readers. When she's not writing, you can find her enjoying good music, reading a book, or spending quality time with her family.

×

Webinar: How to Get 100% Scores on Core Web Vitals

Join Joe Williams & Aleksandar Savkovic on 29th of March, 2021.

Do you like what you read?

Get the Latest Updates

Share Your Feedback

Please insert Content

Thank you for your feedback!

Do you like what you read?

Get the Latest Updates

Share Your Feedback

Please insert Content

Thank you for your feedback!

Want to Experience the Cloudways Platform in Its Full Glory?

Take a FREE guided tour of Cloudways and see for yourself how easily you can manage your server & apps on the leading cloud-hosting platform.

Start my tour