README

WP_Error was a cool feature in 2007 but today we should throw exceptions.

Features

Handles HttpExceptions like WP_Error's
Supports custom handlers for custom exceptions
Compatible with other exception handlers (e.g. Whoops)

Requirements

PHP 8.1+
WordPress 6.x

We aim to support versions that haven't reached their end-of-life.

Installation

composer require attributes-php/wp-exceptions

How it works?

Once the ExceptionHandler is registered, you can start throwing exceptions

use Attributes\Wp\Exceptions\ExceptionHandler;

ExceptionHandler::register();

How HttpExceptions are displayed?

WordPress itself handles how an HttpException is displayed to the user. In a nutshell, those exceptions are converted into a WP_Error which is then handled by WordPress via wp_die function.

This means, that the following types of requests are supported:

✅ Ajax
✅ JSON
✅ JSONP
✅ XMLRPC
✅ XML
✅ All other types e.g. HTML

How to send custom HTTP headers?

throw new HttpException(headers: ['My-Header' => 'Value 123']);

How to add custom handlers?

$exceptionHandler = ExceptionHandler::getOrCreate();
$exceptionHandler->onException(CustomException::class, fn($ex) => echo "A custom exception has been raised");

Ensure to add handlers which supports all types of possible requests e.g. JSON, XML, etc

Sage theme support

If you are using Sage theme, you would need to register or re-register this exception handler after the application is configured. Otherwise, this exception handler might be overrided.

// themes/sage/functions.php

Application::configure()
    ->withProviders([
        App\Providers\ThemeServiceProvider::class,
    ])
    ->boot();

ExceptionHandler::register(force: true); // We are using force true in case the ExceptionHandler has been registered before e.g. in a plugin

WP Exceptions was created by André Gil and is open-sourced software licensed under the MIT license.

attributes-php / wp-exceptions

Maintainers

Details