Download the PHP package dakujem/strata74 without Composer

✋ Please note

This is a backport of the original package dakujem/strata, for PHP 7.4 only.

Based on v1.0 release of the PHP 8 version.

After updating to PHP 8, just change the requirement to dakujem/strata.
Chances are, you need not do anything else.
If your classes directly implement strata interfaces, you will only need to update type hints of implemented methods (pin, replaceContext, pass, explain, tag and convey).

The PHP 8 version has improved key handling (supports integer keys, aligned with PHP array key handling) and full test coverage.

Strata

Contracts and implementations for layered exception handling mechanisms.

TL;DR

Native PHP exceptions allow to carry a string message and an integer code.

👉 That's not enough. 👈

Embrace context-enabled exceptions.

Context-enabled exceptions

• convey information to clients
• carry meta-data for developers

HTTP client error example:

Internal logic fault:

The meta-data can be used by server-side error handlers to report detailed data.

The client-facing data can be used by client apps and displayed to end users or processed programmatically.
This is especially useful for API+client app architecture (JS widgets, PWAs, mobile apps, etc.).

Processing context using error handlers

Typically, your apps will have a global error handling mechanism in place, be it a try-catch block in your bootstrap, error handling middleware or a native error handler.

Something along these lines:

In Laravel, for example, it's usually the App\Exceptions\Handler class that handles the exceptions.
In Slim, middleware is used for error handling.
Symfony will also catch all exceptions and errors, and it is possible to customize the handling logic.

All these rely on developers to come up with specific exceptions that carry specific context, like Guzzle's RequestException carries HTTP request and response.
And that's fine. By all means, do create specific exceptions for specific purposes.
Strata will help enable context support by implementing a single interface (SupportsContextStrata) and using a single trait (ContextStrata).

There's also times when one does not need specific exceptions, but still wishes to pass contextual data to global error handlers.
Strata provide exceptions for common HTTP responses.

To add context for reporting or logging or to add information targeted at front-end consumers, strata provide both the interfaces and the implementations.

Examples

Example of an exception handler in Laravel (JSON API):

Example of processing the internal context for improved Sentry reports:

Notable contracts for API design

Contracts for automatic error handling, especially useful for HTTP APIs:

• IndicatesClientFault 4xx
• IndicatesServerFault 5xx

Common HTTP 4xx exceptions

This package provides exceptions for common 4xx HTTP status responses:

• 400 BadRequest
• 404 NotFound
• 403 Forbidden
• 401 Unauthorized
• 409 Conflict
• 422 UnprocessableContent

See the HTTP status reference for more information.

Build your own

The strata contracts and traits allow and encourage developers to come up with their own exceptions for specific use-cases easily.

If only selected mechanisms are needed, use the table below to pick specific interfaces and traits:

To provide throwables with HTTP capabilities, implement the following trivial interfaces:

• SuggestsErrorMessage to suggest error messages to your error handlers
• SuggestsHttpStatus to suggest HTTP status codes to your error handlers