Container Laravel Package

Technical Evaluation

Architecture fit

• illuminate/container is a DI/IoC container: it resolves constructor dependencies, binds interfaces to implementations, and manages singleton lifecycles. As a TPM, treat it as plumbing, not a product surface — it earns its place because it is the substrate for testability (swap bindings for mocks), modularity (interface bindings per feature), and third-party substitutability (swap a payment gateway by rebinding one interface).
• It is Laravel-shaped, not framework-neutral. It implements PSR-11 (Psr\Container\ContainerInterface) but its differentiating capabilities — tag()/tagged(), when()->needs()->give() contextual binding, extend(), call() method injection, makeWith() — are Laravel extensions. Any architecture that depends on those is coupled to Laravel, and any portability claim must be scoped to get/has only.
• Fit is strongest when the container is the single composition root for an application. It is a poor fit as a bolt-on alongside a second container (e.g., Symfony's DI) in the same request lifecycle, and an unnecessary dependency in ultra-constrained or non-Laravel projects where PHP-DI or hand-rolled factories suffice.

Integration feasibility

• In Laravel: zero-cost. It ships inside laravel/framework; no install, no wiring, no decision to justify beyond "we're on Laravel."
• Standalone: mechanically easy, organizationally risky. composer require illuminate/container works, but you inherit illuminate/contracts and a small dependency tail, and you take on composition-root responsibilities Laravel normally handles for you (bootstrap, singleton registration, request/console lifetimes).
• Governance constraint that matters more than the code: the repository is a read-only subtree split of laravel/framework. You cannot patch it in place and have the patch survive; contributions go upstream to the monorepo. That converts any necessary fix into a monorepo PR, a release-train wait, or a vendored fork — a real schedule risk if this package ever becomes load-bearing in a non-Laravel context.

Technical risk

• Static global state. Container::getInstance() / setInstance() mutate process-wide state. In long-running workers (queue consumers, Octane-style servers, Horizon) this is the primary leakage and cross-tenant-contamination vector. Mitigation is a policy decision, not a code fix: ban setInstance() in application code and enforce by static analysis.
• Circular dependencies fail at runtime, not at build time. CircularDependencyException surfaces during resolution — i.e., in staging or production, on the code path that first asks for the object. No compile-time graph validation is provided.
• Portability trap. Teams that adopt tag()/extend()/when() and later want out of Laravel face a non-trivial rewrite. Encode "PSR-11 subset only" as an architecture rule if exit optionality matters.
• Metadata is unreliable — flag this in diligence. Stars (≈35k) and releases are attributed to the laravel/framework monorepo, not the split package; Dependents: 0 is a measurement artifact of subtree splits, not evidence of no adoption. The reported last release date (2026-10-27) is in the future relative to normal reporting and should be reconciled against the actual tag history before anyone cites it in a decision memo. Do not use star count or dependent count as adoption evidence here; use "bundled with every Laravel install" instead.
• Runtime floor. The available analysis cites PHP 8.3+. Verify against your platform matrix — this is the single most likely blocker for legacy estate integration, and it should be confirmed from composer.json rather than taken second-hand.

Key questions

1. Is Laravel the composition root for this system, or are we introducing a second container alongside an existing one? If the latter, who owns conflict resolution?
2. Do we need Laravel-only features (tagging, contextual binding, extend()), or is a PSR-11 subset sufficient? The answer determines our exit cost.
3. What is our policy on Container::getInstance() / setInstance(), and how is it enforced? Without an enforced rule, long-running workers are a latent incident.
4. Which PHP versions must we support, and does the package's requirement exclude any of them?
5. Who is accountable for upstream contribution if we need a change, given the read-only split and monorepo release cadence?
6. In multi-tenant or serverless contexts, is one container per request/tenant the design — and is that documented?

Integration Approach

Stack fit

• Laravel / Lumen / Laravel-adjacent (Octane, Horizon, Nova): native fit, no decision required. This is the default and the answer for the large majority of adopters.
• Standalone PHP with Laravel-style conventions: acceptable if a deliberate composition root is built and the PSR-11 subset discipline is agreed up front.
• Hybrid Symfony/Laravel or other rigid DI frameworks: poor fit. Two containers resolving the same object graph invites double-instantiation, static-resolution conflicts, and debugging that no one enjoys. Prefer one container per process.
• Non-PHP or embedded/constrained environments: out of scope.

Migration path

• Greenfield on Laravel: nothing to do; container is present. Effort is entirely in convention — where bindings live (a service provider per module), naming, and singleton-vs-transient policy.
• Brownfield on Laravel: introduce incrementally. Start by binding interfaces for new modules only; wrap legacy classes in container-managed facades to avoid a refactor cliff; migrate service-by-service behind the interface, not file-by-file.
• From another DI container: do not big-bang. Map existing registrations to bind()/singleton()/instance(), run both in parallel behind a thin adapter, migrate new code first, and delete the old container only after the graph is fully served. Budget time for the resolution-order and lifecycle semantics that differ (singleton scope, deferred resolution, extend() post-processing).
• Explicit non-goal: do not migrate working code purely for consistency. The value is in test seams and substitutability, not in container purity.

Compatibility

• PSR-11 compliance buys get()/has() interop; it does not buy feature parity. Any custom resolver, decorator, or third-party integration should target ContainerInterface so it survives a container swap.
• Coexistence with other PSR-11 containers is possible at the interface boundary but not at the feature level; tagged(), when(), and build() are Laravel-only and will break under a different implementation.
• Watch illuminate/contracts version alignment if standalone — mismatches with the Laravel major in use are a common source of confusing resolution errors.

Sequencing

1. Confirm the runtime constraint (PHP version, illuminate/contracts compatibility) against the platform matrix. This gates everything else.
2. Decide container ownership: one composition root per process; document it.
3. Publish binding conventions before writing bindings — interface-per-module, provider-per-module, singleton-vs-transient criteria, no setInstance().
4. Pilot on one bounded module with a mocked-dependency test to prove the testability payoff and to flush out lifecycle assumptions.
5. Instrument resolution in non-production: log or trace make() calls during the pilot to find hot paths and accidental double-resolution before they become performance surprises.
6. Roll out module by module; keep legacy paths behind facades until the graph is fully owned.
7. Harden: static-analysis rule banning global instance mutation; a lint or test that asserts no circular dependencies are introduced on critical paths.

Operational Impact

Maintenance

• Near-zero by design. The package moves with the Laravel release train; upgrades arrive as part of the framework bump you were already doing. Standalone consumers take on the version-pinning burden that Laravel users don't feel.
• The real maintenance cost is upstream, not local. Because the repo is a read-only subtree split, local fixes are not durable. If your team ever needs a behavior change, the cost is a monorepo contribution plus a release wait — or an internal fork with a standing rebase tax. Budget for this explicitly if you're a standalone adopter; budget zero for it if you're on Laravel.
• Convention decay is the actual long-term cost. Bindings scattered across providers, singleton/transient chosen by vibe, and no ownership of the container config turn into a graph nobody can reason about. Maintenance burden here is a discipline problem the package cannot solve for you.

Support

• Mature, widely adopted, well-documented in practice; the effective support channel is the Laravel ecosystem (docs, community, Stack Overflow), not a dedicated support contract.
• Standalone adoption is a minority path: the community and issue traffic live in the monorepo and are overwhelmingly Laravel-framed. Expect to debug edge cases — especially around global instance state and non-Laravel bootstrapping — with less community precedent than a Laravel user would have.
• Internal support obligation: someone must own the binding conventions and review changes to the composition root. That's a small but permanent role, not a one-time task.

Scaling

• Request throughput: resolution is reflection-based on first request and cached thereafter; the dominant cost is first-resolution, not steady state. This is rarely the bottleneck, but it should be measured rather than assumed for high-fan-out graphs.
• Horizontal scale: stateless per-request containers scale cleanly. The risk concentrates in long-lived processes — queue workers, Octane, Horizon — where a stale singleton or mutated global instance persists across jobs and tenants. Scaling out the worker fleet scales the blast radius of that class of bug.
• Organizational scale: the container is what lets parallel teams work without merge conflicts — new features register bindings, they don't edit shared factories. That's the strongest scaling argument for it, and it's a team-throughput argument more than a runtime one.
• Graph complexity is the real ceiling. Deep dependency chains slow resolution and obscure failures; tagging and contextual binding help, but they also make the graph harder to read. Watch for tagged() collections becoming unbounded lists that no one can enumerate.

Failure modes

Ramp-up

• Fast for anyone with PHP experience: the five core methods (bind, singleton, instance, make, resolve) cover ~90% of daily use. A developer is productive in an afternoon.
• The advanced surface is where mistakes live: contextual binding, extend() decorators, makeWith() for parameterized resolution, call() method injection, resolver hooks, and overriding make()/build(). These should be gated behind review, or they become clever one-offs nobody else can maintain.
• Ramp-up plan: a short internal guide covering (a) the five core methods, (b) our binding conventions, (c) the banned patterns — setInstance(), tag() in portable code, constructor-time make() that hides cycles — plus one worked module as a reference implementation. Half a day of enablement, and it prevents most of the failure modes above.
• Onboarding signal to watch: if new engineers can add a feature without touching the composition root, the conventions are working. If every feature requires editing a shared provider file, the architecture has drifted and the container is becoming a god object.