Proxy Laravel Package

Product Decisions This Supports

• Cross-cutting concerns without touching domain code. Proxy/interception lets us add logging, metrics, caching, audit trails, authorization checks, transactions, and retry/circuit-breaking at the service boundary rather than sprinkling them through business logic. This directly supports any roadmap item gated on observability or compliance evidence.
• Build vs. buy. The alternative is hand-writing decorator classes for every interface we want to instrument — N interfaces × M concerns of boilerplate that drifts and rots. This package collapses that into generated proxies plus a small amount of configuration. The buy case is strong if we already have interface-driven services; weak if our services are concrete god-classes.
• Architecture direction. Choosing it signals a commitment to interception as the mechanism for cross-cutting behavior, which implies: interfaces everywhere, a proxy-generation step in the build/deploy pipeline, and container wiring discipline. That is a real org constraint, not just a library pickup.
• Concrete use cases worth scoping:
  • Wrapping third-party SDK clients (payments, email, KYC, shipping) with retry, timeout, and failure-isolation behavior so vendor flakiness doesn't leak into product flows.
  • Instrumenting the repository/service layer for latency and error-rate dashboards, and for per-tenant usage metering if we monetize by consumption.
  • Feature-flag gating and multi-tenant scoping at the service method level, where HTTP middleware can't reach — queue workers, console commands, scheduled jobs, service-to-service calls.
  • Lazy instantiation of expensive services so cold-start latency and memory stay inside budget on latency-sensitive endpoints.
• Framework fit is itself a product decision. This is a Yii-family package (yiisoft/*). If the stated stack is Laravel, adopting it means maintaining a non-idiomatic seam in the codebase — a decision to make deliberately, not incidentally.

When to Consider This Package

Consider it when:

• The codebase is interface-driven PHP 8.x, and the services you want to instrument are ordinary classes/interfaces that can be subclassed.
• You need interception below HTTP: jobs, workers, console commands, domain services, outbound vendor calls. This is the strongest argument — Illuminate\Pipeline and HTTP middleware simply don't cover these paths.
• You're on Yii3 and already using yiisoft/di; the proxy factory integrates with the container and is the idiomatic mechanism, so you inherit convention rather than inventing one.
• You want declarative cross-cutting behavior for a bounded, enumerated set of services — not a general AOP platform with pointcut expressions.
• You can absorb a code-generation step: proxies must be built and cached during deploy/opcache warmup, and the artifact needs to be part of the release process.

Look elsewhere when:

• You're a Laravel shop. Use middleware, the container's extend/decorator bindings, or a small laravel-decorator-style package. The framework mismatch is a permanent tax on onboarding, review, and debugging for a capability Laravel already gives you 80% of.
• You need to intercept final classes, static methods, or property access — generated-subclass proxies structurally cannot do this.
• You need real distributed tracing. Proxies help you wire instrumentation; the answer is OpenTelemetry instrumentation, and this package is at best a convenience.
• You need pointcuts and advice (full AOP) — that's Ray.Aop's problem space.
• The codebase is small. Two explicit decorators cost less than a dependency, a generator, and a build step. Adopt when the count of decorated interfaces crosses roughly five to ten.
• Community-size risk is unacceptable for the critical path. 22 stars is a genuine signal. Mitigations: check the release cadence (a 2026-04-02 release suggests active maintenance), confirm it's Yii core-team maintained, pin versions, and wrap it behind our own thin abstraction so replacement is a one-file change. Don't let it become load-bearing in a way only one engineer understands.

Verify the current API surface against the upstream docs before committing — the capabilities above are the category's standard contract, and specifics of generation and DI wiring should be confirmed in a spike.

How to Pitch It (Stakeholders)

To executives (one paragraph): We're evaluating a small, permissively licensed (BSD-3-Clause) PHP library that lets us attach logging, caching, access checks, and retry behavior to existing services without rewriting business logic. The upside is less duplicated code, faster delivery of any feature gated on auditability or reliability, and fewer bespoke wrappers per vendor integration. The exposure is deliberately contained: it's a development-time convenience, not a runtime service we depend on for uptime. The two risks are that it's a small-community project and that it comes from the Yii ecosystem rather than Laravel — both are manageable. We'd de-risk with a one-sprint spike, pin the version, and keep it behind our own interface so we can swap it out without touching product code.

To engineering (one paragraph): It's an interception layer: it generates proxy classes that wrap your services and run behavior before and after method calls. It fits naturally with Yii3 DI; on Laravel it overlaps with HTTP middleware and container decorators, so we'd reserve it for entry points middleware can't reach — queue jobs, console commands, scheduled tasks, and domain service boundaries. Requirements are interface-based design and a proxy-generation step in the build pipeline (cache warmup, opcache, deploy artifact) — no generation, no interception. Two hard limits to design around: it can't touch final classes, statics, or properties, and it is not a tracing solution. Keep all interception configuration in one place, behind a thin internal abstraction, so the dependency stays replaceable and the blast radius stays small.