Download the PHP package rasuvaeff/yii3-api-problem without Composer

rasuvaeff/yii3-api-problem

Русская версия

RFC 9457 Problem Details for Yii3 and any PSR-7/PSR-15 application. Use the value object directly, turn it into a hardened response, or catch exceptions with middleware that has explicit production and debug disclosure policies.

Using an AI coding assistant? llms.txt is a compact API reference with the package rules and copy-ready examples.

Requirements

• PHP 8.3-8.5.
• A PSR-7 implementation and PSR-17 response/stream factories.
• A PSR-15 stack only when using ProblemDetailsMiddleware.

Installation

The examples use nyholm/psr7 as the PSR-7/17 implementation:

Usage

Create an RFC 9457 document in an action and return it as a PSR-7 response:

The response status comes from the problem. Its content type is always application/problem+json, and it always carries X-Content-Type-Options: nosniff.

Value object

type, title, status, detail, and instance are reserved and cannot be used as extension names. Optional null members are omitted during serialization.

InvalidParam provides a stable shape for field validation failures:

This produces the invalid-params extension shown in RFC 9457 examples. RFC 9457 permits extension members but does not standardize a universal validation error schema; consumers must opt into this package-defined shape.

Transport headers

Pass headers when a problem needs HTTP metadata such as Retry-After or WWW-Authenticate:

Header values may be strings or lists of strings. Caller headers cannot override the mandatory application/problem+json content type or nosniff policy.

Throwing a problem

An action may throw a problem intended for the client:

ProblemDetailsMiddleware preserves this explicitly supplied document. In particular, an intentional detail is not removed in production.

Exception middleware

Place it outside the application handler that may throw. Successful responses pass through unchanged. In production, ordinary exception messages and traces are never copied into the response. With debug: true, detail contains the exception message and the trace extension contains its stack trace. Never enable debug mode in production.

Exception reporting

The middleware can report the original exception before returning a safe response. Implement ThrowableReporterInterface as a small adapter to your logger, Sentry, or another observability system:

The reporter receives both generic exceptions and ProblemDetailsException, is not called for successful responses, and must not throw.

In a Yii3 application you can hand the reporter to the middleware through params instead of redefining the middleware definition — see Yii3 configuration.

The default mapper handles these cases:

Configured entries match the exact class, not parent classes or interfaces:

Implement ExceptionMapperInterface when mapping needs domain-specific logic.

Yii3 configuration

The config plugin binds ProblemDetailsResponseFactoryInterface, the concrete DefaultExceptionMapper, and ProblemDetailsMiddleware. It deliberately does not bind ExceptionMapperInterface or ThrowableReporterInterface, because the application owns those replaceable choices.

Default params:

throwable_reporter names a ThrowableReporterInterface implementation the config plugin resolves from the container and passes to the middleware:

With the default null (or the key absent), the middleware gets no reporter. The package never binds ThrowableReporterInterface itself — the application owns the implementation and its construction, just like the mapper.

Your PSR-17 implementation must provide ResponseFactoryInterface and StreamFactoryInterface in the container. Override the middleware definition when supplying a custom mapper, CorrelationIdProvider, or when the reporter needs wiring beyond a plain container-resolved class.

Correlation ID

Implement this package's small CorrelationIdProvider interface and pass it to the middleware. A non-null ID becomes the problem instance:

The adapter keeps rasuvaeff/yii3-correlation-id optional.

When to use which

Use this package when you want a small RFC 9457 value object plus a configurable exception mapper, typed validation extension, transport headers, exception reporting, production/debug disclosure policy, correlation ID integration, and Yii3 config-plugin wiring.

Use crell/api-problem when you need its mature generic-PHP ecosystem, XML serialization, or its existing PSR-7/15/17 integration. It is an established package; this library is an opinionated Yii3-oriented alternative, not a claim that the generic niche is empty.

If yiisoft/error-handler already formats every exception in your application, use one error formatting path. This middleware must sit outside a throwing handler; it cannot reformat a response already produced by another error handler.

Security

• Keep debug false in production. Ordinary exception messages and stack traces are considered sensitive.
• Treat extension values as response data. JSON encoding prevents structural JSON injection but does not make credentials or personal data safe to expose.
• Problem type URIs are identifiers, not automatically fetched documentation.
• ProblemDetailsException is an explicit disclosure boundary: only throw it with client-safe detail, extensions, and headers.
• Reporter implementations must not throw and must redact sensitive request data before sending it to third-party telemetry.

Examples

See examples/ for executable scripts covering manual responses, exceptions, typed validation extensions, middleware setup, custom mappings, reporting, and transport headers.

Development

PHP and Composer are run through Docker in this repository; the equivalent Make targets are make build, make test, make psalm, make mutation, and make bench.

License

The package is released under the BSD 3-Clause License.