Download the PHP package componenta/http-respond-interceptor without Composer

Componenta HTTP Respond Interceptor

HTTP interceptor for componenta/interceptor that turns a route handler result into a PSR-7 response through Componenta\Http\Responder.

Русская документация

Requirements

• PHP 8.5+

PHP 8.5 is required because #[Respond] accepts closures and first-class callables directly in attribute arguments.

Boundary

This package contains:

• RespondInterceptor
• #[Respond]
• #[Created] as a shortcut for status 201

It does not create the HTTP application, router, or PSR-17 factories. Those parts are provided by componenta/app-http, componenta/router-app, componenta/http-psr-*, and componenta/http-responder.

Installation

Quick Start

#[Respond] extends Componenta\Interceptor\Attribute\Intercept. AttributeInterceptor creates RespondInterceptor through the container, and RespondInterceptor calls Responder::respond($status, $result, $contentType).

Response Factory

The last argument of #[Respond] is an optional response factory. It receives a configured Closure $respond as its first argument and the result returned by the downstream handler/interceptor chain as its second mixed argument. Any parameters after those two are resolved through Componenta DI's normal callable-invocation pipeline. The factory must return a ResponseInterface.

The $respond closure is already bound to the attribute's status, content type and headers. Calling $respond() uses the original downstream result. Calling $respond($replacement) passes the replacement to Responder::respond() instead; an explicit null is distinct from omitting the argument. Configured headers are applied by $respond before it returns, so the factory may still replace them afterwards.

PHP 8.5 allows a static closure directly in an attribute:

First-class callables are supported as well:

#[Created] supports the same final factory argument.

Additional services can be injected after the first two reserved arguments. For example, when the application binds Symfony's SerializerInterface, it can be requested directly by type:

The third and later parameters are not limited to serializers; any service resolvable by Componenta DI can be requested there. The first two positions always remain the configured respond closure and downstream result. This lets a factory serialize or project an unsupported DTO first and then hand the transformed value back to the normal Responder without injecting Responder itself.

If a factory returns anything other than ResponseInterface, RespondInterceptor throws UnexpectedValueException.

Status Codes

#[Respond(204)] returns an empty response because this behavior belongs to Componenta\Http\Responder.

HTTP Headers

Pass response headers through #[Respond] or #[Created] with the headers argument. Header values may be a string or an array of strings.

The interceptor applies configured headers after Responder::respond(). They are therefore also applied when the handler already returns a ResponseInterface, and a configured header replaces an existing header with the same name. The configured $respond closure applies these headers to every response it builds. A factory receives the original downstream result separately and can call $respond() or $respond($replacement); after the closure returns, the factory remains free to override those headers.

The interceptor can be configured directly in the same way. Direct construction also requires a DI-aware CallableInvokerInterface; normal attribute-based construction receives it from the container automatically:

Migration From 1.x

Version 2.0 requires PHP 8.5+, but the existing argument order is preserved. The factory is appended after headers, so existing positional calls remain valid:

The factory can be supplied by name without filling unused optional arguments:

Ordering With Serialization

A factory that needs the original DTO should normally serialize inside the factory instead of placing #[Serialize] below #[Respond]:

The factory then receives the original User, may inject SerializerInterface, and can call $respond($serializer->serialize($result, 'json')). If #[Serialize] is still placed below #[Respond], the factory's second argument is the serialized inner-chain result rather than the original DTO.

Scope

RespondInterceptor and #[Respond] are restricted to Scope::HTTP. They run only when the router integration sets the HTTP scope on CallableContextInterface.

License

MIT