Interceptors Laravel Package

Getting Started

Start by installing the package via Composer (composer require spiral/interceptors), then register InterceptorsBootloader in your app’s bootstrap sequence. The core concept is method interception — wrapping calls to public methods (e.g., in services or controllers) to inject cross-cutting concerns like logging, caching, or retry logic. The simplest first use case is wrapping a service method to log входящие вызовы (input) and выходящие (output) data by defining an interceptor class that implements Spiral\Interceptors\InterceptorInterface, then tagging it with #[Interceptor] and attaching it to methods via attributes like #[Loggable].

Implementation Patterns

Use interceptors for:

• Logging & Monitoring: Wrap methods to record timing, arguments, and return values (e.g., for APM or debugging).
• Retry & Circuit Breaker: Add resilience by retrying failed method calls (e.g., network calls, external APIs).
• Caching: Intercept method results and serve cached responses based on arguments (with cache key generation).
• Authorization/Validation: Enforce security policies before method execution without polluting business logic.

Typical workflow:

1. Define a reusable attribute (e.g., #[Cacheable]) using Spiral\Attributes\Attribute, optionally with properties like ttl or key.
2. Implement an interceptor class that inspects method reflections and attributes, deciding whether to delegate, short-circuit, or wrap execution.
3. Register interceptors globally or per-class via #[Intercept(...)] attribute on target classes/methods.
4. Use InterceptedProxy or framework-provided integration (e.g., Spiral Framework’s DI container) to apply proxies where applicable.

For performance-critical apps, combine interceptors with lazy initialization and ensure they are non-intrusive and stackable (support multiple interceptors per method).

Gotchas and Tips

• Proxy Overhead: Interceptors rely on runtime proxy generation. In dev, ensure caches (like bin/rebuild) are cleared after changing interceptor definitions. Production builds benefit from pre-generated proxies.
• Return Type Alignment: Interceptors must preserve original method signatures including return types—using yield from, __call(), or wrong typing breaks type safety.
• Circular Dependencies: Avoid registering interceptors on services that are used during interceptor setup (e.g., injecting LoggerInterface inside an interceptor that itself is used during container initialization).
• Attribute Scoping: Interceptors apply only to public methods of intercepted classes. Private/protected methods, static methods, or traits are ignored unless handled explicitly.
• Debugging Tip: Use #[Debug] or custom logging in interceptors with debug-only guards to avoid side effects in production.
• Extension Point: Implement Spiral\Interceptors\ProviderInterface to dynamically register interceptors at runtime (e.g., based on config or environment).