Multi Tenant Laravel Package

Technical Evaluation

tenancy/multi-tenant is the actively maintained successor to stancl/tenancy, and it is the de facto standard multitenancy package for Laravel. The 5.9.1 patch re-adds Laravel 9 support to the 5.x line, which is a compatibility correction rather than a feature release: 5.9.0 evidently tightened the supported framework range, and 5.9.1 walks that back so Laravel 9 applications can still consume the current 5.x branch.

Architecture fit. The package is opinionated about how tenancy is wired into the framework. It owns tenant resolution (domain, subdomain, path, or custom resolvers), bootstrapping (switching database connections, cache stores, filesystem roots, queue configuration, Redis prefixes), and a lifecycle of events around tenant initialization and teardown. This is a good fit if your application is already conventionally Laravel-shaped: Eloquent models, service container, facades, queued jobs, and the standard HTTP kernel. It is a poor fit if the application has heavy global state, long-lived workers that predate the package's bootstrapper model, or significant non-Laravel code paths that touch the database directly. The central TPM decision is single-database (row-scoped via a tenant column) versus multi-database (one schema/database per tenant). The package supports both, but they carry very different operational profiles — see Operational Impact.

Integration feasibility. Integration effort is moderate and well-documented. Expect to define a Tenant model, configure a resolver, register middleware, and audit every place the application assumes a single connection. The package provides tenant-aware jobs, cache, filesystem, and Redis out of the box, which removes the most painful custom work. The genuinely hard part is not installing the package; it is auditing existing code for implicit global assumptions — raw queries against the default connection, hard-coded storage paths, singleton services that capture tenant data at container-build time, and any code that runs before the tenant is resolved.

Technical risk. Several areas warrant explicit scrutiny before committing:

• Package coupling and upgrade drag. The 5.9.0 → 5.9.1 episode is itself the signal. A patch release that changes the supported Laravel range means your framework upgrade cadence is coupled to this package's cadence. If you are pinned to Laravel 9 for compliance or platform reasons, 5.9.1 restores your ability to take 5.x fixes — but you should assume future minors may drop Laravel 9 again. Pin deliberately and track the supported-version matrix as a standing risk.
• Central vs. tenant connection leakage. The most common production incident class with this package is a query accidentally executing against the central connection (or against the previously resolved tenant) because the tenant was not initialized, or because a queue worker did not re-bootstrap between jobs. This is a correctness and data-isolation risk, not just a bug.
• Queue and scheduler semantics. Tenant-aware jobs require the tenant identifier to be serialized with the job and re-initialized on the worker. Long-running workers (Horizon, Octane, Swoole) amplify teardown mistakes.
• Migration orchestration. Per-tenant migrations introduce a fan-out operation that must be idempotent, observable, and resumable at scale.
• Ecosystem compatibility. Packages that open their own connections, cache aggressively at boot, or assume a single filesystem root may need per-tenant configuration.

Key questions for the engineering team.

1. Which tenancy model are we committing to — single-database with row scoping, or database-per-tenant — and what drives that choice (isolation requirements, tenant count, migration cost, backup/restore granularity)?
2. Does any part of the codebase bypass Eloquent and touch the database through raw PDO or a second connection?
3. What is our Laravel version commitment over the next 12–18 months, and does 5.9.1's Laravel 9 support materially extend the life of our current stack or merely delay an upgrade?
4. Are we running long-lived workers (Horizon, Octane)? If so, what is our testing story for tenant leakage across job boundaries?
5. What is the tenant onboarding and offboarding runbook — who provisions a database, runs migrations, and verifies isolation?
6. Do we have any contractual or regulatory data-residency requirement that forces physical separation per tenant rather than logical scoping?

Integration Approach

Stack fit. The package targets Laravel 9, 10, and 11 on the 5.x line as of 5.9.1. It assumes PHP 8.x, Composer, and a standard Laravel service-provider bootstrapping model. If the surrounding platform is Laravel-native, integration is largely additive: a config file, a Tenant model, middleware, and a set of bootstrappers. If the platform is a hybrid (e.g., Laravel alongside a legacy PHP service, or a Laravel API behind a non-Laravel gateway), the tenant resolution boundary must be agreed at the edge and passed through unambiguously, otherwise the package will resolve tenancy from the wrong signal.

Migration path. For an existing single-tenant application, the realistic path is staged:

1. Instrument first. Introduce the resolver and middleware in identify-only mode, logging what tenant would have been resolved, without switching connections. This surfaces routing and domain assumptions cheaply.
2. Choose the model and prove it on one tenant. Stand up the tenancy configuration for a single internal or pilot tenant. If database-per-tenant, provision the database, run the package's migration commands, and verify the bootstrappers switch connection, cache, filesystem, and queue correctly.
3. Audit for leakage. Systematically grep for direct connection usage, hard-coded storage paths, and cache keys without tenant scoping. Convert tenant-scoped artifacts to use the package's tenant-aware facilities.
4. Move queue and scheduler paths. Convert jobs to the tenant-aware base class, ensure tenant identifiers are serialized, and test worker re-bootstrap explicitly.
5. Backfill and cut over. Migrate existing data into the tenancy model, then flip resolution from log-only to enforcing.

The 5.9.1 release specifically de-risks step 1 for Laravel 9 shops: it means you do not have to bundle a framework upgrade into the tenancy integration. Keeping those two changes separate is worth insisting on — a combined framework-plus-tenancy upgrade is materially harder to debug and to roll back.

Compatibility. Treat the Laravel version constraint as a first-class dependency in planning. Because 5.9.0 briefly narrowed support and 5.9.1 restored it, pin the package to a specific minor and require an explicit review before any bump. Record the supported matrix (Laravel 9/10/11) in the platform runbook and re-verify it at each framework upgrade. Also verify the status of secondary packages that interact with connections, queues, and storage — those are where incompatibilities actually surface, not in the tenancy package itself.

Sequencing. Land tenancy in a horizontal slice (resolution, bootstrapping, middleware) before touching feature code, so the isolation boundary is testable in isolation. Then convert features by domain area, starting with read paths and ending with writes and background processing. Do not attempt to convert queue and scheduler behavior in the same change set as the HTTP path; they fail differently and need separate verification.

Operational Impact

Maintenance. The package is actively maintained with a steady release cadence and responsive maintainers, which is the main reason to prefer it over the archived stancl/tenancy. The maintenance burden that lands on your team is not the package itself but the ongoing audit discipline: every new feature, every new background job, and every third-party package added must be checked against the tenancy boundary. Budget for this as a permanent tax on feature work, not a one-time integration cost. The 5.9.1 patch also illustrates that framework-version support can move in patch releases, so the dependency must be watched, not just installed.

Support. Community support via GitHub issues and documentation is good but not contractual. For a revenue-bearing multi-tenant platform, designate an internal owner for tenancy — someone accountable for the version matrix, the isolation test suite, and the onboarding runbook. Without a named owner, isolation regressions accumulate silently until a customer notices.

Scaling. Scaling characteristics differ sharply by model:

• Single-database, row-scoped: simpler operations, one backup and migration target, but every tenant table needs a tenant column and every query needs the scope enforced. Noisy-neighbor effects are real, and per-tenant restore or export is awkward. Migration fan-out is trivial, but large-tenant performance requires index design attention.
• Database-per-tenant: strong isolation and clean per-tenant backup, restore, and deletion, but migration fan-out becomes a batch operation that must be observable and resumable, connection counts grow with tenant count (watch pool sizing), and provisioning must be automated from day one.

In both models, the failure mode to design against is connection-pool exhaustion and migration storms during deploys that touch many tenants.

Failure modes. The ones worth writing runbooks for:

• Cross-tenant data exposure from a missed tenant initialization or a stale connection in a worker. This is the highest-severity failure and should be covered by automated tests that assert isolation on every endpoint touching tenant data.
• Wrong-tenant writes in queues where the tenant ID is not serialized or is lost on retry.
• Partial migration across tenants leaving schema skew; requires a migration status table and a safe retry path.
• Central-connection writes that silently succeed because the default connection is still configured.
• Storage and cache collisions where tenant-scoped paths or keys are not namespaced, producing data bleed between tenants.
• Deploy-time contention when a release runs migrations across thousands of tenants simultaneously.

Ramp-up. Assume meaningful ramp-up for the team beyond reading the docs. The concepts are not difficult, but the failure modes are subtle and only surface in background processing and edge routing. Plan for: a short internal enablement session on the bootstrapper lifecycle; a written tenancy conventions doc covering connection usage, cache keys, storage paths, and job patterns; and an isolation test harness in CI before the first external tenant is onboarded. Realistic estimate: one to two weeks for a mid-level Laravel engineer to be productive, and considerably longer before they reliably avoid the leakage failure modes without review. The highest-leverage investment is the conventions doc plus the CI isolation suite — those convert per-engineer vigilance into a repeatable check.

Recommendation. Adopt 5.9.1 as the baseline for new multitenancy work, specifically because it preserves Laravel 9 support and lets the tenancy integration proceed independently of a framework upgrade. Pin to 5.9.x, designate an internal owner, and make the tenancy model decision (single-database vs. database-per-tenant) before any code is written — that choice determines the operational shape and is expensive to reverse.