Download the PHP package componenta/interceptor without Composer

Componenta Interceptor

Middleware-style interceptor pipeline for PHP callables. Wrap any function, method or closure with cross-cutting logic (logging, caching, transactions, authorization, serialization) declared either via pipe() or method-level attributes.

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

Installation

Requirements

• PHP 8.4+
• psr/container
• componenta/di (CallableExecutorInterface, FactoryInterface, ParametersResolver)
• componenta/reflection (lazy reflector resolution)
• componenta/config (optional ConfigProvider integration)

Related Packages

Quick Start

Core Concepts

Interceptor

A class implementing InterceptorInterface. Receives the execution context and a continuation handler; may act before/after, short-circuit, or transform the result.

Context

Immutable object carrying the callable, its parameters, arbitrary attributes, and a lazily-resolved reflector. Mutators return new instances:

Pipeline

InterceptingExecutor composes interceptors into a pre-built chain on first use. Execution order is FIFO — the first registered interceptor is outermost (runs first in the call direction, last on unwind):

pipe() returns a new immutable pipeline:

Short-circuit

An interceptor may return without invoking the handler (auth rejections, cache hits, maintenance screens). The pipeline stops, and the value bubbles back through outer interceptors.

Attributes

Declare interceptors on methods via #[Intercept]:

Resolution is driven by AttributeInterceptor (register it once in your pipeline). The interceptor instance is built via FactoryInterface with the declared params. Attributes are read as layers wrapped around the method, from outside in — the topmost attribute is the outermost layer (enters first, returns last), the bottommost attribute is closest to the method body.

Put entry-side interceptors (authorization, rate limits, caching gates) above result-side ones (response formatting, serialization, pagination). The method's return value flows outward through the inner layers first, so a serializer placed below a response wrapper gets the raw value and passes the serialized string up to the wrapper:

Attribute classes can also implement InterceptorInterface directly — they are instantiated through native PHP attribute construction:

Scopes

Restrict where an interceptor runs by implementing Componenta\Scope\ScopedInterface on the attribute or on the interceptor instance:

The integrator signals the current scope by setting a context attribute before the pipeline runs:

Attribute-level scope takes priority over instance-level scope. Interceptors without either ScopedInterface always match.

Built-in scopes: HTTP, CONSOLE, GRPC, QUEUE, WEBSOCKET. Custom scopes can be represented by Componenta\Scope\ScopeName or by a package-specific enum implementing Componenta\Scope\ScopeInterface.

Callback Interceptors

Build interceptors from closures without dedicated classes:

Parameter Resolution

Register ParameterResolvingInterceptor to enrich the callable's parameters through DI before downstream interceptors see them:

This lets attribute interceptors read resolved arguments (e.g., $ctx->parameters for cache keys).

Caching

AttributeInterceptor caches attribute resolution on two levels:

1. Candidates per signature — #[Intercept] instances are created once per method and reused.
2. Composed chains per terminal — stored in a WeakMap keyed by the terminal handler; innermost link holds the terminal weakly, so GC reclaims entries when the terminal goes out of scope (e.g., when pipe() discards an old pipeline).

No configuration required — caching is always on. Closures bypass the cache (no stable signature).

Container Wiring

Register the module's ConfigProvider in your application:

It binds CallableContextFactory, AttributeInterceptor, and PipelineInterface. The PipelineInterface service is intended for HTTP route handler execution and is built by HttpInterceptorPipelineFactory:

1. ParameterResolvingInterceptor is always registered first, so callable parameters are resolved through DI before application interceptors run.
2. Additional interceptors are read from ConfigKey::HTTP_INTERCEPTORS.
3. Each configured item may be a container service id or an InterceptorInterface instance.

Typical HTTP configuration:

componenta/router-app consumes PipelineInterface when it executes route handlers. Applications usually configure the interceptor list in their src/ConfigProvider.php.

License

MIT