Weave Code
Proxy Laravel Package
yiisoft/proxy
yiisoft/proxy provides lightweight proxy objects for PHP that defer instantiation until first use, enabling lazy service loading and cleaner dependency injection without changing your application code. Part of the Yii 3 ecosystem.
General purpose proxy
Frequently asked questions about Proxy
- What does yiisoft/proxy actually do?
- yiisoft/proxy is a Yii3 plumbing library that generates runtime proxy subclasses of a target class or interface, deferring real instantiation until first use. Methods on the proxy delegate to the wrapped instance, so a dependency stays type-compatible while construction is lazy or intercepted. It is not an application feature; it is a low-level utility for dependency injection and definitions use cases.
- How do I install and wire yiisoft/proxy in a Laravel app?
- You can install it with composer require yiisoft/proxy, but there is no Laravel service provider, config file, or facade. You bind the proxy manager as a singleton yourself and point generated code at a writable path such as storage/framework/proxies. Laravel version constraints are not implied, so installation risk is low, but the wiring is entirely manual.
- Doesn't Laravel's container already do lazy resolution?
- Laravel's container already resolves bindings lazily, so for most ordinary deferral needs a binding or ContextualAttribute is simpler. A proxy earns its place when a constructor-injected concrete class or a final-ish collaborator must stay type-compatible at the call site. If a container binding or a thin decorator solves the case, prefer that instead.
- Should I use a proxy or a hand-written decorator?
- A hand-written decorator is usually clearer for a small, stable set of methods because it is explicit and statically analyzable. A runtime proxy is better when the target class is large, final, or changes often and you cannot add an interface. Proxies also help for third-party SDK clients with heavy constructors, but they make the object graph less obvious.
- Which PHP versions and syntax does yiisoft/proxy support?
- The dominant technical risk is runtime code generation from reflection, which is coupled to PHP's type system. New syntax such as readonly classes, property hooks, asymmetric visibility, and DNF types can require library updates, and a PHP minor upgrade can break generation at boot rather than at test time. Pin PHP versions in CI and verify generation for every target class construct you rely on.
- Does it correctly proxy final methods, static returns, by-reference parameters, and magic methods?
- Faithful forwarding matters, so you should verify the generator reproduces return types, static returns, by-reference parameters, magic methods like __call and __get, and readonly properties before adopting. Proxying final methods and final classes is a common constraint to test, since final blocks conventional subclassing and mocking. Gaps show up as subtle bugs rather than loud failures, so build a spike that covers your real target classes.
- Can I pre-generate proxies at build time instead of at runtime?
- Yes, pre-generating proxies at build time is strongly preferable to writing them at runtime on a read-only container filesystem. Runtime generation introduces writable-path requirements, multi-worker races, and OPcache staleness. If you adopt the library, make generation a deploy step and point output at a build directory rather than storage at request time.
- Will proxies break debugging, dd(), or static analysis?
- Proxied objects have a different get_class(), appear oddly in stack traces, and can confuse dd(), var_dump(), IDE navigation, and static analysis. Doctrine and some Laravel internals occasionally make decisions based on concrete class identity. Constrain proxy use to a small, documented set of dependencies so the object graph stays understandable.
- Is yiisoft/proxy production-ready and well maintained?
- yiisoft/proxy is maintained by the Yii core team, but it has low external adoption and single-vendor stewardship, which is a bus-factor concern. It is BSD-3-Clause, so licensing is fine as long as you retain attribution. A recent release is a positive maintenance signal, but it does not replace crowd-sourced battle testing outside Yii3.
- When should a Laravel team avoid yiisoft/proxy?
- Use it surgically for legacy concrete-class dependencies you cannot refactor, third-party SDK clients with expensive constructors, or test doubles where final blocks conventional mocking. Do not use it as a primary architectural tool in Laravel, because container bindings, ContextualAttribute, and thin decorators cover most cases. If you cannot name a case that fails both alternatives, do not adopt it.
Weaver
How can I help you explore Laravel packages today?