Framework Laravel Package

Technical Evaluation

What this package actually is. tenancy/framework is not an end-user multi-tenancy package. It is the low-level engine that sits underneath tenancy/tenancy — it wraps Laravel's Illuminate\Foundation\Application and kernel bootstrap so that multiple tenant "applications" can be instantiated, booted, and torn down inside a single PHP process. It provides the hook/lifecycle system, the tenant-aware container indirection, and the application-swapping primitives that the higher-level package composes into a usable API. Our teams will almost never call it directly; they will consume it transitively.

Architecture fit. Good fit if the target is a Laravel monolith or a small fleet of Laravel services that need hard tenant isolation (separate databases, separate config, separate service providers), particularly where per-tenant bootstrapping must happen inside long-running processes — queue workers and Octane are the whole reason this layer exists. Poor fit if the requirement is merely row-level scoping on shared tables; that is solvable with a global scope and a middleware, and pulling in an application-swapping framework for it is over-engineering with real debugging cost.

The trade-off is explicit: this package buys process-level isolation at the price of owning Laravel's bootstrap lifecycle. It reaches into framework internals (container, kernel, bootstrappers, config repository). That is a deliberate coupling, and it is the primary source of both its power and its fragility.

Integration feasibility. Feasible but should be scoped as a platform decision, not a feature-level one. Practical constraints:

• Consume it transitively. Add tenancy/tenancy to the application; let Composer resolve tenancy/framework. Direct dependency on the framework package should require an explicit architecture exception, because that pins us to an internal API we do not control.
• Version matrix must be verified, not assumed. Confirm the illuminate/* and PHP constraints in the package's composer.json against our current Laravel version and our next two planned upgrades before committing. The failure mode here is not "install fails" — it is "installs, boots, and misbehaves."
• Isolation must be proven, not assumed. The acceptance gate for any pilot is a bidirectional isolation test suite: a tenant context cannot read central data, and a central context cannot leak into a tenant. Assertions belong in CI, not in a manual QA pass.

Technical risk. Rated high, with the risks concentrated in three areas:

The star count deserves a fair reading: it is low because it is infrastructure that nobody adds directly, not because it is unused. But it also correctly signals that this is not an artifact with an ecosystem of answers, blog posts, and Stack Overflow coverage around it. When it breaks, we are reading the source.

Key questions to resolve before a go decision.

1. Is the framework API versioned as stable/semver, or is it explicitly internal and subject to refactor in the parent's minor releases?
2. What is the stated and tested support matrix for Laravel, PHP, Octane, and Horizon/queue workers?
3. Is there a documented security disclosure process, and what is the anticipated response time for a leakage-class bug?
4. Who is on the hook for maintenance — is there a sponsorable maintainer or a plausible commercial support route?
5. What is the migration story when the parent package advances a major version? Is there a deprecation window?

Integration Approach

Stack fit. Laravel-only. No value outside a Laravel/PHP runtime, and no meaningful prior art to reuse outside that ecosystem. The package presumes our services are on a modern Laravel version with a conventional bootstrap; services that have heavily customized their kernel or bootstrappers will fight it.

Migration path. Do not migrate the estate. Sequence it as follows:

1. Spike (1–2 weeks). Stand up a disposable Laravel service, wire tenancy/tenancy, and exercise the three scenarios that actually break multi-tenant systems: a queue job dispatched in tenant A, an Octane request cycle in tenant B immediately following tenant A, and a rollback/failure during tenant provisioning. Success criteria are written down before the spike starts.
2. Isolation harness (parallel). Build the bidirectional CI test suite during the spike, not after. This is the artifact that outlives the decision — it is what lets us accept Laravel upgrades later.
3. Pilot (one service). Choose a service with real tenants but bounded blast radius: not auth, not billing, not anything holding cross-tenant reporting. New-build is strongly preferred over retrofit.
4. Standardize or stop. Only after the pilot survives a Laravel minor upgrade cleanly do we make it a platform standard. If the pilot requires patching the framework package, that is a stop signal.

Compatibility and sequencing constraints. Framework and parent package must move in lockstep; pin both exactly and treat upgrades as change-managed events rather than routine composer update drift. Add tenancy/framework to the "must re-run isolation suite" list on every Laravel minor and patch release. If any service runs Octane or long-lived workers, that service is a higher tier of testing than an ordinary request/response service.

Wrapping. If we conclude we need to touch framework primitives directly, put an internal adapter in front of them so call sites depend on our interface, not theirs. Given the package's instability profile, this is cheap insurance and also makes a future swap to a competing approach (e.g., a simpler connection-switching or schema-per-tenant model) a contained change rather than a rewrite.

Operational Impact

Maintenance. Budget recurring engineering time, not a one-off integration cost. Realistic ongoing load: tracking upstream releases, re-running the isolation suite on framework and Laravel bumps, and periodically reconciling our tenant provisioning and migration tooling against upstream changes. Assume a small number of engineer-days per quarter at steady state, spiking to weeks on a Laravel major upgrade.

Support. Community-only. There is no vendor to escalate to, no SLA, and no commercial backstop visible at 13 stars. Our escalation path for a leakage-class bug is our own engineers reading framework source under incident pressure. If this package sits under revenue-bearing tenant data, that gap should be explicitly accepted by an accountable owner, or closed by a retainer/consulting arrangement.

Scaling. Two axes matter. Tenant count drives connection and provisioning overhead — multi-database tenancy means a connection per active tenant, so connection pool sizing, database server limits, and per-tenant migration fan-out become capacity-planning concerns rather than routine ones. Tenant size is fine; the model scales with the number of isolated units, not the volume in any one. Long-running workers are the dangerous surface: pool exhaustion, stale tenant context, and config caching bleed all show up there first.

Failure modes to instrument for, in priority order.

1. Context leakage — a request or job resolving against the wrong tenant. Highest severity, lowest visibility. Mitigate with defensive assertions in the container resolution path and per-request tenant-ID logging.
2. Connection exhaustion — tenant connections not released on worker recycle.
3. Migration drift — some tenant databases ahead of others with no reconciliation job; this compounds silently until a deploy breaks on one tenant.
4. Partial provisioning — a failed tenant creation leaving an orphaned database and half-configured record.
5. Bootstrap fragility after upgrade — everything installs, but a bootstrapper no longer runs in the tenant context.

Ramp-up. Steeper than typical Laravel package adoption. Engineers must reason about Laravel's bootstrap lifecycle, service container behavior, static state, and process lifetime — not just request handling. A competent Laravel team should expect roughly two to four weeks before they can debug context-leakage issues independently rather than by trial and error. Plan for one or two engineers to go deep and become the internal owners; distributing shallow knowledge of this layer across the team produces confident misdiagnoses.

Recommendation. Conditional proceed, scoped to a pilot, consumed transitively through tenancy/tenancy and never as a direct dependency. Gate the decision on a clean spike covering queue and Octane behavior plus a passing bidirectional isolation suite, and on written answers to the ownership and support questions above. If the actual requirement turns out to be shared-database row scoping, stop — the operational burden here is not justified.