Php Debug: Mastering 3 Essential Strategies 2025

Why PHP Debug Skills Are Essential for WordPress Success

Effective PHP debug techniques are critical for maintaining a healthy WordPress website. Choosing the right approach for a given situation, from a white screen of death to a subtle logic error, can save hours of frustration and ensure quick problem resolution.

Quick PHP Debug Reference:

Basic Output Methods: echo, print_r(), var_dump() – 40% of developers use these frequently for quick checks.
File Logging: error_log(), file_put_contents() – 5% of developers use these for persistent, non-intrusive debugging.
Advanced Interactive Debugging: Xdebug with IDE integration – 55% of developers have tried this for complex issues.
WordPress-Specific: Debug plugins like Query Monitor for deep, non-intrusive analysis.
Configuration: Proper php.ini settings for error_reporting and display_errors are foundational.

The challenge isn’t just knowing these tools exist, but understanding when and how to use each one effectively. A simple syntax error might only need a quick var_dump(), while complex application logic requires stepping through code with a full debugger. The key is building a systematic approach that scales from quick fixes to deep investigation.

For WordPress site owners, the stakes are high, as unresolved errors can impact user experience, search rankings, and revenue. I’m Kevin Gallagher, a WordPress developer with fifteen years of experience. At wpOncall, I’ve helped maintain over 2,500 websites, and I know that proper debugging is key to protecting your WordPress investment.

The Debugging Spectrum: From Simple Outputs to File Logging

When a WordPress site breaks, you need debugging methods that work fast. The PHP debug spectrum ranges from quick-and-dirty solutions that provide immediate answers to sophisticated logging systems that track problems over time. The fundamental choice is between seeing results on-screen immediately or collecting information silently in the background.

The Quick and Dirty: Using echo, printr, and vardump

Dropping a quick var_dump($variable); to see what’s inside is a common and effective tactic. About 40% of developers regularly use these basic output methods because they are simple, reliable, and always available.

echo: The simplest function, echo, is perfect for confirming code execution paths or displaying simple strings and numbers. See the official echo documentation for its usage.
print_r(): This function is used for arrays and objects, displaying their structure in a human-readable format. It’s great for understanding data structure but omits data types. You can learn more from the PHP manual’s detailed explanation.
var_dump(): The most detailed of the three, var_dump() reveals a variable’s data type, value, and length. This is invaluable for tracking down type-related bugs where "5" is not the same as 5. The var_dump documentation covers its capabilities.

Here’s a comparison:

Feature	`echo`	`print_r()`	`var_dump()`
Data Types	No (outputs string representation)	No (outputs human-readable string)	Yes (outputs type, value, and length)
Arrays/Objects	Converts to string (“Array” or “Object”)	Yes (readable structure)	Yes (recursive, detailed structure and types)
Return Value	None	Returns string if `true` passed, else `void`	Returns `void`
Use Case	Simple strings, numbers, flow check	Readable array/object inspection	Detailed inspection of any variable, including types

These methods require zero setup and provide instant feedback. However, they are intrusive, dumping output directly onto the page, which can break layouts or AJAX responses. Accidentally leaving a var_dump() on a live site is a security risk and requires careful cleanup.

The Silent Observer: Logging with errorlog and fileput_contents

When you can’t disrupt the page output, file logging is your secret weapon. This approach separates your debugging information from your application output. While only about 5% of developers primarily use logging, it’s a powerful technique for debugging background processes or intermittent bugs.

error_log(): This function writes messages to your server’s error log or a custom file, allowing you to record data without affecting page output. A simple error_log("Debug: User ID is " . $user_id); creates a timestamped entry. The error_log documentation shows how to customize its behavior.
file_put_contents(): This function offers more control, letting you create and append to custom log files with specific formatting, such as file_put_contents('debug.log', print_r($data, true), FILE_APPEND);. See the fileputcontents documentation for options.

File logging provides a persistent record of errors that survives page refreshes, keeping your layouts pristine. The main challenges are the need to manually check log files and the risk of them becoming unwieldy. Log files in public directories can also expose sensitive information, so they must be secured. Our guides on WordPress Error Logs and How to Enable Error Logging in WordPress explain how to manage these files securely.

Mastering Interactive PHP Debug with Xdebug

If basic output functions are a magnifying glass, Xdebug is a full diagnostic laboratory. This powerful PHP extension transforms PHP debug from guesswork into a precise, step-by-step investigation. It allows you to follow your code’s execution in real-time, examine variables at any point, and even test theories by changing values mid-session. It’s no surprise that 55% of developers have used Xdebug; its level of control is a game-changer.

At wpOncall, Xdebug is our go-to tool for stubborn WordPress issues, from plugin conflicts to misbehaving theme functions. Its core capabilities include Step Debugging (walking through code line by line), Profiling (identifying performance bottlenecks), and Code Coverage (seeing which code runs during tests). You can explore all features on the official Xdebug website.

Step Debugging: This is the most common use case. It allows you to pause your script at any point (using breakpoints) and inspect the state of your application, including variable values and the call stack.
Profiling: While step debugging is for logic errors, profiling is for performance issues. When enabled, Xdebug can generate a cachegrind file that records every function call, how long it took, and how many times it was called. Tools like KCacheGrind (for Linux) or Webgrind (a web-based tool) can then visualize this data, showing you exactly which functions are the slowest part of your application. This is invaluable for optimizing slow-loading pages in WordPress.
Code Coverage: This feature is essential for developers who practice Test-Driven Development (TDD). When you run your automated test suite (e.g., with PHPUnit), Xdebug can track which lines of your application code were executed. It then generates a report, often with color-coding in your IDE, showing you exactly what parts of your code are covered by tests and, more importantly, what parts are not. This helps ensure your tests are comprehensive and reduces the chance of regressions.

Key Features of Xdebug

Xdebug’s power comes from its combined features, which provide complete visibility into your code.

Step-by-step execution: Pause and walk through your code line by line as it runs.
Breakpoints: Set strategic pause points in your code without adding any debug statements.
Variable inspection: View the contents of all local and global variables at any breakpoint.
Stack traces: See the full execution path of functions that led to the current point in your code.
Conditional breakpoints: Configure breakpoints to pause only when specific conditions are met (e.g., when $i > 10).
Runtime variable modification: Change variable values on the fly to test different scenarios without restarting.
Improved var_dump() output: Automatically improves var_dump() for better readability, even when not actively debugging.

These features are provided by the PHP Xdebug extension and integrate with your code editor.

Setting Up Xdebug for Local PHP Debug

Setting up Xdebug is an investment that saves countless hours of future frustration. The process involves installing the extension, configuring PHP, and connecting it to your IDE.

Install the extension: Use the Xdebug installation wizard. Paste your phpinfo() output into the wizard, and it will provide custom installation instructions for your specific environment.
Configure php.ini: Find your php.ini file and add the necessary lines. The zend_extension directive points to the Xdebug file. Set xdebug.mode = debug to enable step debugging and xdebug.start_with_request = yes to begin debugging on every request. Finally, configure xdebug.client_host and xdebug.client_port (usually 9003) to match your IDE’s settings. Remember to restart your web server after making changes.
Integrate with your IDE: For VS Code, install the “PHP Debug” extension and use the default “Listen for Xdebug” configuration. PhpStorm has excellent built-in support; simply validate your setup and configure server mappings.

A Practical Debugging Session

Using Xdebug transforms mysteries into solvable puzzles. Here’s a typical workflow:

Set Breakpoints: In your IDE, click in the margin next to a line number in a PHP file to set a breakpoint (a red dot will appear).
Start Listening: Activate the debugger in your IDE to listen for incoming connections.
Trigger the Code: Refresh the page or perform the action in your browser that executes the code containing the breakpoint.
Debug: Your IDE will pause execution at the breakpoint. From here, you can use the debug controls to steer your code, inspect all available variables in the variables panel, and analyze the call stack to understand the execution flow. Key controls include:
- Continue: Resumes the program’s execution until it hits the next breakpoint or the script finishes.
- Step Over: Executes the current line of code and moves to the next line in the same file. If the current line is a function call, it executes the entire function without going inside it. This is useful when you trust a function works correctly and don’t need to inspect its internal logic.
- Step Into: If the current line is a function call, this command will move the debugger into the first line of that function, allowing you to debug it line by line. If it’s not a function call, it behaves like “Step Over.”
- Step Out: If you have stepped into a function and want to quickly finish its execution and return to the line where it was called, use “Step Out.”

This interactive approach is how we at wpOncall Fix WordPress Critical Errors. We can step through the actual problem code, see exactly where it fails, and understand why, allowing for precise and effective solutions.

Configuring Your Environment for Effective Debugging

Debugging without proper error reporting is like trying to solve a mystery blindfolded. The infamous “white screen of death” (WSOD) is a perfect example—a fatal error occurs, but PHP isn’t configured to tell you why. This can be a compile-time error (like a syntax mistake) or a runtime error (like calling a non-existent function).

Before diving into advanced PHP debug techniques, your environment must be configured to show you what’s wrong. This involves setting up PHP to report errors correctly and understanding the difference between development and production settings. For broader context, see our WordPress Troubleshooting resources.

Configuring PHP’s Error Reporting Levels

PHP provides fine-grained control over which errors are reported and how they are displayed. This is managed through several key directives in your php.ini file.

error_reporting: This acts as your error filter. For development, set it to E_ALL to capture every possible error, warning, and notice. This helps you write cleaner, more robust code.
display_errors: This controls whether errors appear in the browser. Set it to On during development for immediate feedback. This must be set to Off on a live production server to avoid exposing sensitive information like file paths or database details.
log_errors: This should always be set to On in both development and production. It ensures a permanent record of all issues is kept for later review.
error_log: Use this to specify a path for your log file, separating your application’s errors from general server messages.

To find your php.ini file, create a PHP file with <?php phpinfo(); ?> and look for “Loaded Configuration File.” After editing php.ini, you must restart your web server. For more details, see the PHP manual on error reporting configuration.

Overriding Configuration Without php.ini Access

If you can’t access php.ini (a common scenario on shared hosting), you can still control error reporting:

Using ini_set(): You can use ini_set('display_errors', '1'); and error_reporting(E_ALL); at the top of your script. Its main limitation is that it’s executed at runtime. If your script has a parse error (like a missing semicolon), PHP won’t even get to the ini_set() line, and you’ll still see a white screen. It’s a good tool for temporarily increasing verbosity within a specific function or file you’re debugging.
Using .htaccess (for Apache servers): If your hosting environment allows it, you can set PHP flags in your .htaccess file. This is processed before PHP scripts are executed, so it can catch parse errors. Add these lines to the .htaccess file in your root directory:
```
php_flag display_errors On
php_value error_reporting E_ALL
```
Remember to remove these from your production site’s .htaccess file, as they pose a security risk.

When facing a WSOD, always check your server’s error logs first, as detailed in our Fix WordPress Errors Guide.

Best Practices for a Clean PHP Debug Workflow

An effective PHP debug workflow extends beyond finding errors to managing the entire lifecycle of debug information. A messy process can introduce new bugs or security vulnerabilities.

Use Environment-Specific Configurations: Your error settings should differ between environments.
- Development: This is your local machine. Here, you want maximum verbosity. error_reporting should be E_ALL, and display_errors should be On. You want to see every notice, warning, and error immediately so you can fix it.
- Staging: This should be a near-identical copy of your production server. display_errors should be Off, but log_errors must be On. The goal is to test how your application behaves with production-level error handling.
- Production: This is the live site. display_errors must be Off. log_errors must be On, and the error_log file must be in a secure, non-public location. Error reporting can be toned down from E_ALL to something like E_ALL & ~E_DEPRECATED & ~E_STRICT to avoid filling logs with non-critical notices.
Manage Logs: Use log rotation to prevent log files from consuming excessive disk space. A busy site can generate large logs quickly.
Add Context: Include timestamps, file paths (__FILE__), line numbers (__LINE__), and relevant variable values in your log messages to make them actionable.
Secure Logs: Store log files outside the public web root. For WordPress, the default debug.log is in the public wp-content directory. Change this by defining a custom path in wp-config.php: define( 'WP_DEBUG_LOG', '/path/outside/webroot/wp-errors.log' );
Remove Debug Code: Clean up all var_dump(), echo, and other temporary debug statements before deploying to production. To prevent accidental exposure, wrap debug code in conditional checks that only run in a development environment: if (defined('WP_DEBUG') && WP_DEBUG === true) { error_log('Debug message'); }
Use Version Control: Keep temporary debug code out of your main branches. Use feature branches for debugging and ensure all log files are listed in your .gitignore file.

Adopting these practices, as detailed in our guide on Debugging in WordPress, will save time and prevent security issues.

Advanced Debugging Strategies and Tools

While basic methods and Xdebug cover most scenarios, PHP debug extends further into specialized territory. For complex applications, frameworks like WordPress, or tricky database issues, advanced tools offer solutions for problems that would otherwise be difficult to solve.

Using Debug Plugins in WordPress

WordPress developers need to inspect what’s happening under the hood without breaking the front-end display. Specialized debug plugins are the perfect solution.

Query Monitor is a lifesaver for WordPress developers. It adds a comprehensive debug panel to the admin bar, showing database queries, PHP errors, hooks and actions, HTTP API calls, and more. This information is displayed non-intrusively and is only visible to logged-in administrators, which is a major security advantage over public error displays.

With Query Monitor, you can log custom variables using do_action('qm/debug', $variable);. The plugin provides a holistic view of each page request, helping to identify performance bottlenecks and plugin conflicts. Its main limitation is that it cannot debug fatal errors that crash PHP before it can load. For those, you’ll still need server error logs. When we investigate complex WordPress Issues at wpOncall, Query Monitor is one of the first tools we use. You can get it from the WordPress plugin repository.

Handling Database Errors

Silent database failures are a common source of bugs. Instead of tedious manual checks, a better approach is to configure PHP to throw exceptions for database errors.

MySQLi: Use mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); at the start of your script. This transforms silent failures into catchable mysqli_sql_exceptions that contain detailed error information.
PDO: This is the default behavior when you set the PDO::ATTR_ERRMODE attribute to PDO::ERRMODE_EXCEPTION during connection. Every database error will automatically become a PDOException.

This exception-based approach provides immediate error detection with detailed stack traces, simplifying your code and making database debugging far more efficient. The PHP manual on exceptions provides comprehensive guidance.

Other Advanced Tools and Techniques

Several other tools can improve your PHP debug capabilities:

Monolog: This is the de-facto standard for logging in the PHP ecosystem. It allows you to create “channels” for different parts of your application (e.g., ‘database’, ‘payments’) and route messages of different severity levels (DEBUG, INFO, ERROR) to different “handlers.” A handler could be a file, a Slack channel, an email, or dozens of other services. For example, you could log all DEBUG messages to a file but send all CRITICAL errors directly to your team’s Slack channel for immediate attention. This level of control is essential for managing logs in a large application.
Nette Tracy: While Query Monitor is WordPress-specific, Tracy is a generic tool for any PHP project. When an error occurs, instead of a plain text message, Tracy presents a full-featured “blue screen” page. This page includes the full stack trace, source code snippets, and the values of all variables at the time of the error. It also features a “debug bar” that can be displayed at the bottom of your site during development, showing information similar to Query Monitor, like database queries and execution time.
Static Analysis Tools (PHPStan, Psalm): A different approach to debugging is to find bugs before you even run the code. Static analysis tools scan your codebase without executing it, looking for a wide range of potential errors. This includes type mismatches, calling methods on potentially null objects, and using undefined variables. Integrating PHPStan or Psalm into your development workflow acts as an automated code reviewer, catching entire classes of bugs proactively and leading to higher-quality code.
json_last_error() & preg_last_error(): Functions to get specific error details after JSON or regular expression operations fail. Use json_last_error_msg() for a more descriptive string.
cURL Debugging: Use the CURLOPT_VERBOSE option and set it to true when making cURL requests. This will output detailed diagnostic information about the connection, including headers and SSL negotiation, which is invaluable for debugging API communication issues.
Shell Command Debugging: Append 2>&1 to commands run with shell_exec() or exec() to redirect the standard error stream (stderr) to standard output (stdout). This makes error messages from the shell command visible in your PHP output or logs.

Mastering these tools will lift your debugging skills, as we cover in our WordPress Tutorials.

Frequently Asked Questions about PHP Debugging

After helping thousands of WordPress site owners at wpOncall, we’ve found the same questions arise repeatedly. Here are concise answers to the most common ones to save you hours of frustration.

What is the difference between vardump(), printr(), and echo?

These three functions all display information but are designed for different purposes:

echo: The simplest choice for outputting strings and numbers. It’s fast, basic, and great for checking if code is being executed.
print_r(): Best for getting a human-readable view of arrays and objects. It shows the structure clearly but does not include information about data types.
var_dump(): The most detailed option. It displays the type, value, and length of variables, making it essential for debugging tricky, type-related issues.

In short, use echo for simple checks, print_r() for array structure, and var_dump() for detailed variable inspection.

Is it safe to use Xdebug on a live production server?

Absolutely not. Xdebug should never be used on a live server. It introduces three major problems:

Performance Overhead: Xdebug significantly slows down your application, which can ruin the user experience.
Security Risks: It opens debug ports that, if misconfigured, could be exploited by an attacker to inspect or manipulate your application.
Instability: It can cause requests to time out or fail, making your site unreliable.

Xdebug is a powerful tool for development and staging environments only. For production, rely on robust error logging and monitoring.

How do I fix the “white screen of death” in PHP?

A “white screen of death” (WSOD) indicates a fatal PHP error that prevents any output. Follow these steps to diagnose it:

Check Server Error Logs: This is the most reliable first step. Look in /var/log/apache2/error.log, /var/log/nginx/error.log, or your hosting provider’s log viewer for the fatal error message.
Enable Error Display (Development Only): In php.ini, set display_errors = On and error_reporting = E_ALL. If you lack access, try adding ini_set('display_errors', 1); error_reporting(E_ALL); to the top of your script (this won’t catch parse errors).
Use WordPress Debug Mode: In your wp-config.php file, set define( 'WP_DEBUG', true );. Also set WP_DEBUG_LOG to true to log errors to wp-content/debug.log and WP_DEBUG_DISPLAY to true to show them on screen.
Isolate the Cause: If it’s a WordPress site, try deactivating all plugins (by renaming the wp-content/plugins folder via FTP) and switching to a default theme. If the site comes back, reactivate them one by one to find the culprit.

This methodical approach turns most PHP debug mysteries into manageable problems by making the underlying error visible.

Conclusion

We’ve journeyed through the diverse landscape of PHP debug strategies, from simple echo statements to the powerful interactive debugging of Xdebug. We’ve seen how file logging provides a persistent record of issues and how specialized tools like Query Monitor can streamline WordPress development.

The key takeaway is that effective debugging requires choosing the right tool for the job. Mastering these techniques transforms debugging from a frustrating chore into a manageable, systematic process. The foundation of it all is a properly configured environment that makes errors visible and logs them securely.

At wpOncall, we apply these expert debugging techniques daily to keep our clients’ WordPress sites running smoothly. We understand that downtime and errors can impact your business, and we know that debugging challenges don’t wait for convenient times.

Choosing the right tool isn’t just about efficiency—it’s about maintaining the health and performance of your WordPress investment. When debugging feels overwhelming, or when you simply need expert hands to ensure your site stays healthy and secure, our team is here to help.

Get expert help with your WordPress site