Siren

Error Handling

How WP_Error and is_wp_error() translate to Siren's typed exception system.

WordPress plugin

Last updated: October 26, 2026

WordPress uses a dual-path error model: some functions return WP_Error objects on failure (which you check with is_wp_error()), while others return false or null. This means every call site needs defensive checks, and the type of error you get is inconsistent across the API.

Siren uses PHP exceptions. When something fails, it throws a typed exception. You catch what you need and let the rest propagate.

// WordPress: check for WP_Error after every operation
$result = wp_insert_post($args);

if (is_wp_error($result)) {
    echo $result->get_error_message();
    return;
}

// Some functions return false instead of WP_Error
$meta = get_post_meta($post_id, '_key', true);
if ($meta === false) {
    // Was it an error, or does the meta just not exist?
}
// Siren: catch typed exceptions
use PHPNomad\Datastore\Exceptions\RecordNotFoundException;
use PHPNomad\Datastore\Exceptions\DuplicateEntryException;

try {
    $program = $this->programs->find($id);
} catch (RecordNotFoundException $e) {
    // The program does not exist — handle it
}

try {
    $this->collaborators->create($data);
} catch (DuplicateEntryException $e) {
    // A collaborator with this email already exists
}

Exception reference

Siren and PHPNomad use typed exceptions that tell you exactly what went wrong. Here are the most common ones you will encounter in extension development:

ExceptionWhen thrown
RecordNotFoundExceptionfind() with a nonexistent ID, or a query that expects exactly one result finds none
DuplicateEntryExceptionCreating a record that violates a uniqueness constraint (e.g., duplicate email)
RestExceptionGeneric REST error that carries an HTTP status code and message. The status defaults to 400
ValidationExceptionRequest validation fails, includes field-level error details
AuthorizationExceptionAuthenticated but insufficient permissions. Carries 400 unless you pass another status
AuthenticationExceptionNot authenticated at all. Carries 400 unless you pass another status

How does this work in REST controllers?

The REST layer turns a RestException, including its validation, authentication, and authorization subclasses, into an error response with the exception’s status. You don’t need to convert those yourself:

  • ValidationException returns a 400 response with field-level errors
  • AuthorizationException, AuthenticationException, and every other RestException return the status they carry, which defaults to 400
  • Any other exception thrown from a controller, RecordNotFoundException and DuplicateEntryException included, returns 500 with “An unexpected error occurred. Sorry, that is all I know.”

So your controller methods can focus on the happy path. Throw a RestException when something goes wrong, and the framework formats the error.

To answer 404 for a missing record, catch RecordNotFoundException and set 404 on the response, or throw a RestException with that status:

use PHPNomad\Datastore\Exceptions\RecordNotFoundException;
use PHPNomad\Rest\Exceptions\RestException;

try {
    $program = $this->programs->find($id);
} catch (RecordNotFoundException $e) {
    throw new RestException('Program not found.', [], 404);
}

An exception thrown from a controller comes back in Siren’s {"error": {"message", "context"}} shape with its status, 401 and 403 included. On WordPress, only a 401 or 403 thrown by middleware becomes WordPress’s {code, message, data} error, with rest_not_logged_in or rest_forbidden. To refuse in WordPress’s shape, write a middleware that throws with the status, the way Siren’s event ingestion middleware does:

namespace MyPlugin\Middleware;

use PHPNomad\Auth\Enums\ActionTypes;
use PHPNomad\Auth\Models\Action;
use PHPNomad\Http\Interfaces\Request;
use PHPNomad\Rest\Exceptions\AuthenticationException;
use PHPNomad\Rest\Exceptions\AuthorizationException;
use PHPNomad\Rest\Interfaces\Middleware;
use Siren\Programs\Core\Models\Program;

class RequireProgramEditor implements Middleware
{
    public function process(Request $request): void
    {
        $user = $request->getUser();

        if (!$user) {
            throw new AuthenticationException('Sign in to use this route.', [], 401);
        }

        if (!$user->canDoAction(new Action(ActionTypes::Update, Program::class))) {
            throw new AuthorizationException("You don't have permission to do that.", [], 403);
        }
    }
}

Return an instance from your controller’s getMiddleware() in place of, or before, createAuthMiddlewareFromCurrentContext().

What should I catch in extension code?

In extension code (listeners, transformers, services), catch the exceptions you can meaningfully handle and let the rest propagate. Common patterns:

// In a transformer: catch RecordNotFoundException when looking up mappings
try {
    $transaction = $this->transactions->find($mappedId);
} catch (RecordNotFoundException $e) {
    // No Siren transaction for this order — return null to skip
    return null;
}

// In a listener: catch and log, but don't crash the event pipeline
try {
    $this->externalService->sync($data);
} catch (\Exception $e) {
    $this->logger->logException($e);
    // The sync failed, but the rest of the pipeline should continue
}

The transformer pattern is especially important. Transformers return null to skip events, so catching “record not found” and returning null is the standard way to handle cases where the data does not exist.

If you do not catch an exception in a listener, it will propagate up and may prevent subsequent listeners for the same event from executing. When in doubt, catch broadly in listeners and log the exception so you can diagnose issues without breaking the event pipeline.

Where to go next

For controllers and middleware in general, see REST API Patterns. For the full REST error response format (including validation error details), see the Resource Reference Introduction.

For the full PHPNomad framework documentation, see PHPNomad.

Your privacy choices

Account, checkout and chat you request work without optional tracking. Choose whether to allow these other uses on this website.

You can change or withdraw your choices at any time using “Privacy choices.” We remember your choice for 180 days. Read our privacy policy.