wp-exceptions

Stop returning WP_Error's. Throw exceptions

View the source repository

Repository snapshot

Files indexed: 17
Revision: main · 2026-01-30T17:01:58Z
Initial page: deterministic repository import; ask Codex to verify and improve it against the source.

README

WP Exceptions

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();

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

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

$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

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.