Multitenant Laravel Package

Technical Evaluation

Architecture fit. phariscope/MultiTenant is a Laravel multi-tenancy package, a category where the architectural decision (single database with tenant scoping vs. database-per-tenant) dominates everything downstream. At version 0.0.29 the package is pre-1.0 and, by semver convention, makes no API stability guarantees. Fit should be judged against a specific tenancy model, not "multi-tenancy" in the abstract: the package must be evaluated on how it resolves tenants (subdomain, custom domain, path prefix, header), how it propagates tenant context into Eloquent, cache, queue, filesystem, session, and logs, and how it handles tenant-aware migrations and seeders. If our product needs a tenancy model the package does not natively model, we inherit an adapter layer plus the maintenance of it.

Integration feasibility. Integration is likely straightforward for the happy path — a service provider, middleware, and a tenancy bootstrapper set — and materially harder at the edges: existing migrations that assume a single database, global scopes that must not leak across tenants, background jobs and scheduled commands that execute outside an HTTP request, and test suites that need a tenant-aware base case. Feasibility should be proven with a time-boxed spike against our real schema rather than a greenfield demo.

Technical risk.

• Version volatility. The release under review jumps 0.0.27 → 0.0.29, skipping 0.0.28 in the visible range, and the only release artifact is an auto-generated compare link. We cannot determine what changed, whether anything broke, or whether a tag was withdrawn. This is a release-hygiene signal, not proof of a defect, but it is a governance risk.
• Isolation correctness. Multi-tenancy failures are silent and severe (cross-tenant data exposure). The package's global-scope approach must be validated against raw queries, DB::table(), relationship traversal, and un-scoped admin paths.
• Long-running process safety. Under Octane, Horizon, or queue workers, tenant context is process-global state that can bleed between requests or jobs if not explicitly reset in finally blocks.
• Abandonment risk. Pre-1.0 packages with sparse release notes are commonly single-maintainer projects; a stall leaves us owning a fork.

Key questions.

1. What tenancy models are supported, and which Laravel and PHP versions are in the support matrix?
2. Is the intended deployment single-database-with-scoping, database-per-tenant, or both — and what is the documented migration path between them?
3. How is tenant context propagated to queued jobs, scheduled tasks, and event listeners, and how is it reset?
4. What were the changes in 0.0.27 → 0.0.29, and why is 0.0.28 absent from the compare range?
5. Is there a published 1.0 roadmap, deprecation policy, and security disclosure process?
6. What is the maintainer bus factor and recent commit cadence?
7. Are there automated tests asserting isolation (negative tests), or only feature tests that exercise the happy path?

Integration Approach

Stack fit. Reasonable for a Laravel application that has not yet committed to a tenancy architecture. The package should be introduced behind our own thin abstraction — a TenantResolver/TenancyService interface owned by us, with the package as one implementation — so the vendor is swappable. This costs a day or two and removes most of the lock-in risk.

Migration path. Sequence: (1) resolve the tenancy model with product and security before any code; (2) spike in a disposable branch against a copy of the real schema, including the two or three most complex existing migrations; (3) retrofit existing migrations and models to be tenant-aware, with an explicit allowlist of genuinely global tables; (4) add a tenant-aware test base class and negative isolation tests; (5) backfill tenants and run a parallel-read comparison against the single-tenant baseline before cutover.

Compatibility. Pin the exact version in composer.json (0.0.29, not ^0.0) and commit the lockfile. Treat every patch bump as a potential breaking change requiring a changelog review and a full test run — at 0.0.x, patch-level breaks are legitimate under semver. Verify compatibility with our Laravel version, PHP version, database driver, and any Octane or queue supervisor in use before the spike concludes.

Sequencing. Do not sequence this work in parallel with an unrelated framework upgrade or a database engine migration; both interact with tenancy bootstrapping and will make failures ambiguous. Gate production use on the abstraction layer being in place and the isolation test suite passing, not on the spike working.

Operational Impact

Maintenance. Expect to absorb upgrade cost on a recurring basis: 0.0.x packages iterate quickly and document sparsely, so each bump requires reading the diff ourselves. Budget a standing allocation of roughly a day per bump for review and regression testing, plus more when a bump touches bootstrappers or global scopes. Owning the abstraction layer also means owning its tests.

Support. Support is community-only, likely a single maintainer and GitHub issues. There is no commercial SLA, no LTS branch, and no documented security response process. For anything touching tenant data this should be treated as an accepted-risk item signed off by security, with a documented fallback: fork the package at a known-good tag and vendor it if upstream stalls.

Scaling. Scaling characteristics are driven by the tenancy model, not the package. Database-per-tenant multiplies connection counts and migration fan-out; single-database scoping adds tenant-predicate indexes to every hot query and makes noisy-neighbour isolation a query-planning concern. Cache and queue keying must be tenant-namespaced or tenants will collide. Validate with a load test at realistic tenant counts and at least one large-tenant-vs-many-small-tenants shape.

Failure modes. The incidents to plan for: tenant context bleeding across requests in a long-running worker (cross-tenant data exposure — highest severity); a queued job dispatching without tenant context and writing to the wrong schema; migration drift where some tenant databases are ahead of others after a partial failure; connection pool exhaustion under database-per-tenant at peak; and cache key collisions after a namespace change. Each needs a detection signal — isolation assertions in CI for the first, a per-tenant schema-version check for the third, connection saturation alerts for the fourth.

Ramp-up. Two to three days for a mid-level Laravel engineer to be productive, most of it spent on the tenancy model and the debugging implications of global scopes rather than the package API. Add an explicit onboarding note that "a query returned no rows" and "a query returned another tenant's rows" look identical in code review, and require the isolation tests to be the arbiter.