How to debug PHP code in WordPress

Debugging PHP code in WordPress involves a systematic approach using built-in WordPress tools, developer plugins, and specialized IDE (Integrated Development Environment) tools like Xdebug.

Here is a guide covering the most effective methods, ranging from simple error logging to advanced step debugging.

1. ⚙️ Basic Error Logging with WP_DEBUG

The most fundamental step is enabling WordPress’s built-in debugging constants, located in your site’s wp-config.php file. This is crucial for viewing PHP errors, warnings, and notices.

1. Access wp-config.php: Connect to your site via SFTP/FTP or use your hosting provider’s file manager. The file is usually in the root directory of your WordPress installation.
2. Enable Debugging: Find the line that says /* That's all, stop editing! Happy publishing. */ and insert the following constants before it:
   PHP
   define( 'WP_DEBUG', true ); // Turns on the main debugging feature
define( 'WP_DEBUG_LOG', true ); // Forces all errors to be saved to a debug.log file
define( 'WP_DEBUG_DISPLAY', false ); // Prevents errors from displaying on the front-end (for production/staging)
@ini_set( 'display_errors', 0 ); // Ensures PHP display errors are off
3. Trigger the Error: Reproduce the issue on your site (e.g., refresh the page where the bug occurs).
4. Check the Log: WordPress will create a file named debug.log inside the /wp-content/ directory. Check this file for a call stack showing the file, line number, and function where the error occurred.

2. 🔌 Plugin-Based Debugging

These plugins simplify the process by providing easy-to-read reports within the WordPress admin area.

A. Debug Bar

• Install and activate the Debug Bar plugin.
• It adds a “Debug” menu item to the top WordPress admin bar, visible only to administrators.
• This bar provides quick access to query data, cache usage, PHP notices, and warnings.

B. Query Monitor

• Install and activate the Query Monitor plugin.
• This is the most powerful tool for tracking performance issues, slow database queries, HTTP API calls, and displaying detailed information about PHP errors and template hierarchy directly in the admin bar. It is essential for tracking down slow code.

3. 🖥️ Advanced Step Debugging with Xdebug

For fixing complex bugs, especially those involving variables changing across multiple functions, Xdebug is the gold standard. It allows you to freeze code execution and inspect every variable at any line.

A. Setup Xdebug

1. Install Xdebug: Xdebug must be installed and configured on your PHP environment (local machine, staging server, or sometimes a managed host allows it).
2. Configure IDE: You need an IDE like VS Code (with the PHP Debug extension) or PhpStorm to listen for the Xdebug connection.
3. Start Listener: Activate the Xdebug listener in your IDE.
4. Browser Extension: Install a browser extension (like “Xdebug Helper”) to easily toggle the debugger on for your specific site.

B. Debugging Process

1. Set Breakpoint: In your IDE, click on the line number in the code file you want to inspect (this sets a “breakpoint”).
2. Trigger Execution: With the listener active, visit the page on your WordPress site that triggers the code.
3. Inspect Variables: The IDE will “catch” the execution at the breakpoint. You can now view all variables, step Over the current line, step Into a function, or step Out of a function to trace the flow of execution.

4. 🖨️ Traditional var_dump() / error_log()

When you can’t use advanced tools, you can always rely on old-school functions to print variable contents.

• For simple output to the browser (use sparingly):
  PHP // Stop execution and print variable details
die( var_dump( $variable_name ) );
• For logging to debug.log (recommended):
  PHP // Sends output to the /wp-content/debug.log file (if WP_DEBUG_LOG is true)
error_log( 'My variable value: ' . print_r( $variable_name, true ) );

How to suppress PHP Notices in debug.log

... TODO