Debugging PHP Applications: A Guide to Error Handling and Logging

Previously in this course, we reached finalizing-mvc-integration-connecting-your-php-architecture, where we successfully tied our database models to our controllers. In this lesson, we move from building features to ensuring our application is maintainable and resilient by mastering the art of debugging.

When a page turns blank or a form stops saving data, your first instinct might be to add echo statements everywhere. While that works for small scripts, professional backend engineering requires a structured approach to identifying and fixing bugs.

Understanding PHP Error Reporting

PHP has an internal configuration that dictates how it handles errors. During development, you want to see every warning, notice, and error immediately. In production, you want to hide those details from users to prevent sensitive information leaks.

The primary configuration happens in your php.ini file or via ini_set() in your bootstrap entry point:

PHP
#6A9955">// Enable all errors during development
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

• display_errors: Controls whether errors are printed to the browser.
• error_reporting(E_ALL): Tells PHP to show every type of error, including "Notices" (like using an undefined variable) and "Warnings."

The "White Screen of Death"

If you encounter a blank page, it usually means a Fatal Error occurred and display_errors is turned off. Always check your server logs (e.g., Apache's error.log or Nginx's error.log) when this happens. These logs are the source of truth for your server.

Built-in Debugging Functions

Beyond logs, we have tools to inspect the state of our application during execution.

1. var_dump() and print_r()

These are the standard tools for inspecting variables. var_dump() is superior because it shows the data type and the length of the string/array.

PHP
$user = ['id' => 1, 'name' => 'Alice'];
var_dump($user); 
#6A9955">// Output: array(2) { ["id"]=> int(1) ["name"]=> string(5) "Alice" }

2. debug_backtrace()

When a function is failing but you aren't sure which controller or model called it, use debug_backtrace(). It provides an array of the call stack, showing you exactly how the code reached the current point.

Implementing Logging

Logging is the practice of recording events to a file instead of displaying them to the user. This is crucial for tracking issues that happen in production.

Instead of writing custom file-handling logic, use PHP’s built-in error_log() function:

PHP
#6A9955">// Log a message to the default server error log
error_log("Attempted to update database for user ID: " . $userId);

#6A9955">// Log to a specific file
error_log("Database connection failed", 3, "/var/log/my-app-errors.log");

Think of logging as a "flight recorder" for your application. If a user reports a bug, you can check the log file for that specific timestamp to see exactly what went wrong.

Hands-on Exercise: Improving the MVC Debugging

In our running project, locate your public/index.php (or wherever your application boots).

1. Add the error configuration block shown above to the top of your file.
2. In your UserController, temporarily force an error by trying to access an undefined index in your data array.
3. Observe how the error output changes when you toggle display_errors to 0.
4. Replace your manual echo debugging with error_log() to record the user's ID whenever a profile is updated.

Common Pitfalls

• Leaving display_errors on in production: This is a security risk. It can reveal database credentials or path structures. Always use an environment configuration file to toggle this.
• Ignoring Notices: PHP "Notices" are not fatal, but they often indicate bugs that will become major issues later (e.g., trying to access an array key that doesn't exist). Address them as they appear.
• Over-logging: Don't log every single variable on every request, or your log files will grow gigabytes in size, making it impossible to find relevant information.

FAQ

• Why does my code fail silently? Check if display_errors is disabled. If it is, your errors are likely being sent to the server log files.
• What is the difference between var_dump and print_r? var_dump is for debugging (shows types/lengths), while print_r is for human-readable output of structures.
• How do I handle production errors properly? Error handling best practices suggest logging errors to a file and showing the user a generic "Something went wrong" message.

Recap

Debugging is not just about fixing bugs; it's about building visibility into your application. By enabling full reporting during development and using error_log for production, you transform your application from a "black box" into a predictable, maintainable system.

Up next: We will dive into Advanced Form Handling, where we'll use these debugging skills to manage complex user input validation and display user-friendly error messages.