Container Laravel Package

Technical Evaluation

Architecture fit

• The package (flightphp/container) is a standalone PSR-style DI container from the Flight micro-framework ecosystem, not a Laravel package. Laravel ships its own container with equivalent and richer semantics (singleton(), bind(), instance(), contextual binding, tagging, deferred providers).
• Net architectural value inside a Laravel application is therefore low-to-none; introducing a second container creates dual source-of-truth for object lifetimes and encourages service-location patterns Laravel's container already discourages.
• Legitimate fit is narrow: standalone PHP scripts, CLI tooling, non-Laravel microservices, or a Flight-based service in a polyglot estate.
• v1.2.0 is additive only: class-name singletons, object-instance singletons, and a fluent set()/singleton() chain. No removals or signature breaks are described.

Integration feasibility

• Two-line adoption (singleton($classOrObject, ?Closure $factory)) — trivial to trial in an isolated spike.
• The chained-call style enables readable bootstrap wiring for DB connections, HTTP clients, and loggers, which is precisely the stated intent.
• Blocked pending answers on autowiring behavior for singleton(SomeClass::class) where the target has constructor dependencies — the only documented example (DateTimeImmutable) is no-arg, so this is unproven.
• Interop with PSR-11 / Laravel's Container::set() delegation is not stated, so a shared-container bridge would need custom glue.

Technical risk

• Medium overall, concentrated in lifetime semantics. Class-based singletons have undocumented construction timing (lazy on first get() vs. eager at registration). This drives correctness in long-running processes.
• No documented reset/clear/flush API for registered singletons. In tests and in Octane/queue workers this is a stale-state and cross-test-pollution hazard.
• Object-instance registration (singleton($existingObject)) binds an already-constructed instance — anything it holds (sockets, PDO handles, open file streams) is retained for process lifetime.
• Single-maintainer, small-surface package; supply-chain and bus-factor risk is real but proportionate to a low-blast-radius utility.
• PHP version floor, security disclosure process, and PSR-11 conformance are all unverified.

Key questions

1. Does singleton(Foo::class) autowire constructor dependencies, or require an explicit factory closure?
2. When is a class-based singleton instantiated — eagerly on registration or lazily on first get()?
3. Is there any forget() / flush() / container-reset mechanism for long-running workers and test isolation?
4. Is the container PSR-11 compliant, and can it wrap or delegate to Laravel's container?
5. What is the minimum PHP version, and what is the maintainer's security-disclosure and release cadence?
6. Does singleton() returning $this alter any prior return contract relied on by existing call sites (verify against v1.1.0)?

Integration Approach

Stack fit

• For Laravel applications: do not adopt. Use app()->singleton() / app()->instance(); the parity is direct and you avoid a second container. Rationale should be recorded so the package isn't re-proposed.
• For standalone CLI, workers, or Flight services: adopt behind a thin internal interface (e.g. a ServiceRegistry wrapper) so the concrete container is swappable.
• If a shared container is genuinely required across both, place a PSR-11 adapter at the boundary rather than teaching application code about flight\Container.

Migration path

• No migration required — this is greenfield adoption, not a replacement. Nothing in the existing Laravel wiring needs to change.
• If trialing in a standalone component: start with one bootstrap file, register only infrastructure singletons (PDO, HTTP client, logger), and keep domain services transient.

Compatibility

• Additive within the v1.x line; no deprecations signalled. Confirm the fluent-return change does not break v1.1.0 call sites that ignored return values.
• Verify PHP version floor against our runtime matrix before pinning; verify behavior under Octane/Swoole and queue workers if any candidate service is long-running.
• Pin to ^1.2 and treat minor bumps as reviewable, given the small maintainer surface.

Sequencing

1. Spike (0.5 day): validate autowiring, laziness, and reset behavior against the six key questions; document findings.
2. Decision gate: confirm the target component is non-Laravel. If it is Laravel, close the evaluation.
3. Pilot in one standalone service with infra-only singletons; add a test that asserts state isolation between test cases.
4. Generalize only if the pilot shows no cross-request state retention.

Operational Impact

Maintenance

• Low carrying cost: small dependency, minimal API. Ongoing burden is version-pinning review, not code maintenance.
• Risk is maintenance continuity — a single-maintainer project means a stalled release could leave us pinned on an unpatched version. Mitigation: wrapper interface permits replacement with league/container or PSR-11 equivalents at low cost.

Support

• Community support only; no commercial backing identified. Internal ownership must be assigned to the adopting team.
• Documentation in the release is example-driven and silent on lifetime semantics; expect tribal knowledge to form around singleton() behavior. Capture it in the spike write-up.

Scaling

• Primary scaling concern is horizontal consistency of singleton state, not throughput. Under PHP-FPM, singletons are per-request and safe. Under Octane, Swoole, or long-lived queue workers, singletons persist across jobs and requests.
• Singletons holding DB connections or API clients must be reconnection-aware and tenant-agnostic; a singleton that caches tenant-scoped or user-scoped state will leak data across requests. This is the single most important operational constraint.
• Absent a reset API, worker recycling (e.g. --max-jobs) becomes the de facto isolation mechanism — plan for it explicitly rather than by accident.

Failure modes

• State bleed across jobs/requests in long-running workers via object singletons or cached state — data-correctness and potential data-exposure severity.
• Test pollution: shared singleton instances persist between test cases, producing order-dependent failures.
• Silent misconfiguration: registering singleton(Foo::class) without a factory, where autowiring is unsupported, fails at get() time rather than at registration — late, harder-to-trace failures.
• Dual-container confusion in mixed codebases: a service resolved from the wrong container yields two instances, defeating the singleton guarantee and producing subtle duplicate-connection or duplicate-client behavior.
• Memory retention from bound object instances holding resources for process lifetime.

Ramp-up

• API surface is learnable in under an hour; the fluent chain is self-documenting.
• Real ramp-up cost is conceptual, not syntactic: engineers must internalize when singletons are constructed and why a second container is prohibited in Laravel code. Budget a short design note plus a lint/review rule blocking flight\Container imports in Laravel application namespaces.
• Estimated effort: 1 engineer-day to spike, document, and land the guardrail; pilot adoption a further 2–3 days including isolation tests.