Advanced Error Handling: Building Production-Grade WordPress Plugins

Previously in this course, we covered Performance Monitoring to track metrics and basic error rates. In this lesson, we shift from observation to active intervention by building a centralized, production-ready error handling system.

Reliable plugins don't just "fail"; they fail gracefully, report the context of the crash, and ensure the user experience remains intact.

The Anatomy of WordPress Error Handling

WordPress provides legacy error reporting via WP_DEBUG and error_log, but these are insufficient for modern, distributable plugins. In a production environment, you cannot rely on server-side log files that you may not have access to.

To achieve professional stability, we must intercept PHP errors, warnings, and exceptions before the environment hides them or, worse, exposes them to end-users. Our strategy involves three layers:

1. Global Exception Catching: Wrapping entry points to prevent site-wide crashes.
2. Custom Error Handlers: Using set_error_handler to convert legacy warnings into actionable exceptions.
3. External Logging: Offloading diagnostic data to external services (like Sentry or custom APIs) to maintain audit trails.

Implementing a Custom Error Handler

We will create an ErrorHandler service that normalizes how our plugin reports issues. By converting PHP notices and warnings into ErrorException instances, we can catch them in a unified try-catch block.

PHP
namespace MyPlugin\Services;

class ErrorHandler {
    public function register(): void {
        set_error_handler([$this, 'handleError']);
        register_shutdown_function([$this, 'handleFatalError']);
    }

    public function handleError($level, $message, $file, $line): bool {
        #6A9955">// Convert non-fatal errors to exceptions
        if (!(error_reporting() & $level)) return false;
        throw new \ErrorException($message, 0, $level, $file, $line);
    }

    public function handleFatalError(): void {
        $error = error_get_last();
        if ($error && ($error['type'] === E_ERROR || $error['type'] === E_PARSE)) {
            $this->logToExternalService($error);
        }
    }

    private function logToExternalService(array $error): void {
        #6A9955">// Implementation for sending payload to Sentry or internal API
        wp_remote_post('https:#6A9955">//logs.example.com/ingest', [
            'body' => json_encode($error),
            'blocking' => false, #6A9955">// Non-blocking: don't slow down the user
        ]);
    }
}

This approach allows us to use standard try-catch blocks throughout our Data Access Objects and Service Providers.

Gracefully Handling Fatal Errors

A fatal error in a WordPress plugin often results in the dreaded "White Screen of Death" (WSOD). While we cannot prevent all memory exhaustion or syntax errors, we can catch shutdown signals.

When a fatal error occurs, we should:

1. Silence the output: Prevent stack traces from printing to the screen, which is a major security risk (learn more about preventing information disclosure).
2. Log the context: Include the current user ID, plugin version, and the relevant request URL.
3. Notify the user (optionally): If in the admin dashboard, show an admin notice indicating a component failure rather than a total crash.

Comparison: Standard PHP vs. Custom Error Handling

Hands-on Exercise: The Error Interceptor

1. Create an ErrorHandler class within your plugin's src/Services directory.
2. Register this service in your main ServiceProvider class.
3. Inject a Logger interface into the ErrorHandler (you can use a PSR-3 compliant library).
4. Throw a deliberate exception in one of your admin controllers and ensure your logToExternalService method is triggered during the catch block.

Common Pitfalls

• Blocking Requests: Never use wp_remote_post with blocking => true inside an error handler. If your logging service is down, your plugin will hang, causing a performance bottleneck.
• Infinite Loops: If your logger triggers an error (e.g., database connection failure), it can cause a recursive error loop. Always wrap your logging logic in a try-catch block that suppresses secondary exceptions.
• Sensitive Data: Never log $_POST or $_GET data directly. These often contain passwords, nonces, or PII. Always sanitize/filter the payload before sending it to an external service.

By standardizing our approach, we ensure that our plugin remains maintainable and transparent, even when things go wrong in production. We are building on the foundations established in our Unit Testing and Integration Testing lessons to ensure that errors are caught not just in development, but in the wild.

Up next: User Feedback Loops — collecting anonymous usage data and error reports to drive product improvements.