Laravel Multi-Tenancy: Four Pieces, No Package

01The shape: one database, a tenant column, four pieces

Every tenant-owned table has a tenant_id column, and 45 models use one trait to enforce it. There is no schema or database per tenant. I chose the shared model because every tenant runs the same schema and the same release, and because the platform operator needs to report across tenants. The cost is that nothing in the database stops a query from reading another tenant’s rows, so the application has to.

02The tenant context: one scoped object

Everything tenant-aware reads the tenant from one class, TenantContext, never from the request. It is registered as a scoped binding, so Laravel throws it away at the start of every request and every queued job. That matters on long-running workers and under Octane, where a plain singleton would carry one tenant into the next request.

It has three methods worth copying. require() returns the tenant or throws with a message naming what needed it. run() binds a tenant for the length of a callback and restores whatever was bound before, even if the callback throws; seeders and console commands use it. And onChange() lets long-lived services clear their per-tenant caches when the tenant changes. The translator and the post type registry both use it, because a cached value from one site showing on the other is a tenant leak too, just not a database one.

// TenancyServiceProvider::register()
$this->app->scoped(TenantContext::class);

// TenantContext
public function run(Tenant $tenant, Closure $callback): mixed
{
    $previous = $this->tenant;
    $this->swap($tenant);

    try {
        return $callback($tenant);
    } finally {
        $this->swap($previous);
    }
}

03Resolution: the host name, and no fallback

A middleware maps the request’s host to a tenant domain before any route runs. Its rules are short, and each one has a test:

• An unknown host returns 404. It never falls back to a default tenant.
• A suspended tenant returns 503.
• A tenant’s other domains redirect permanently to its primary domain, keeping the path and query, so search engines see one host per site.
• Host matching is case-insensitive, and the cache holds only the domain’s id, never a serialized model, so a cached entry can’t carry stale tenant data. Moving a domain clears its cache entry.

The no-fallback rule is the one people skip. A default tenant feels harmless in development, where there is only one tenant, and that is exactly why it is dangerous: the code that relies on it looks correct until a second tenant exists.

04Enforcement: a trait that fails closed

Each tenant-owned model uses a BelongsToTenant trait. It adds a global scope for reads and model events for writes, and every rule in it fails closed:

static::addGlobalScope(new TenantScope);

static::creating(function (Model $model): void {
    $current = app(TenantContext::class)->id();

    if ($current === null) {
        throw TenantNotResolved::forWrite($model::class);
    }

    $model->tenant_id ??= $current;

    if ((int) $model->tenant_id !== $current) {
        throw CrossTenantWrite::for($model::class, $model->tenant_id, $current);
    }
});

static::updating(function (Model $model): void {
    if ($model->isDirty('tenant_id')) {
        throw CrossTenantWrite::reassignment($model::class);
    }
});

• Reading with no tenant bound throws TenantNotResolved instead of returning every tenant’s rows.
• Creating with no tenant bound throws. Otherwise the new row is stamped with the bound tenant.
• Creating a row for a different tenant than the bound one throws CrossTenantWrite.
• Changing the tenant_id of an existing row throws. A row never moves between tenants.

Platform code that genuinely needs every tenant, such as a super admin report, calls Model::acrossTenants(), which removes the scope. It is a static method with a deliberately loud name, so every use shows up in a search and stands out in review.

Two limits are worth knowing. Global scopes apply to Eloquent queries only: the query builder (DB::table()) and raw SQL bypass them, so tenant-owned tables are only queried through their models. And model events don’t fire for mass updates and deletes run on a query, which is why the trait guards creates and single-row updates, and the scope still filters which rows a mass update can reach. Why fail closed beats fail open is argued in full in Multi-tenant isolation.

05Queues: the tenant travels in the payload

A queued job has no host name to resolve a tenant from. The service provider adds the current tenant’s id to every job payload when the job is dispatched, binds that tenant when a worker picks the job up, and restores the previous tenant when the job finishes or fails. A job dispatched with no tenant runs with no tenant, so it can’t touch tenant-owned data by accident: the scope throws.

Queue::createPayloadUsing(fn () => [
    'tenant_id' => app(TenantContext::class)->id(),
]);

Event::listen(JobProcessing::class, function (JobProcessing $event) use (&$previous) {
    $context = app(TenantContext::class);
    $previous[] = $context->current();

    $context->forget();
    if ($id = $event->job->payload()['tenant_id'] ?? null) {
        $context->set(Tenant::query()->findOrFail($id));
    }
});

// JobProcessed and JobExceptionOccurred pop $previous and restore it.

The previous tenant is kept on a stack, not in one variable, because of the sync queue driver. In tests and local development, sync runs the job inside the request that dispatched it, so the request’s tenant has to come back once the job ends.

One trap showed up while writing the test for this. dispatch() returns a pending dispatch that only queues the job when it is destroyed. Inside a short arrow function passed to run(), it can be destroyed after run() has already restored the previous tenant, and the job is queued under the wrong one. The test uses a full closure for that reason, and the comment above it says why.

06The tests that hold it in place

Tenancy code is easy to weaken without noticing, so every rule above has a test. These are the ones I would write first on any Laravel platform:

07Laravel multi-tenant packages: build it, or use stancl/tenancy or Spatie?

Two packages cover most Laravel multi-tenancy needs. Tenancy for Laravel (stancl/tenancy) is built around a database per tenant and also supports a single database with a BelongsToTenant trait; it identifies tenants by domain, subdomain, path or request data. Spatie’s laravel-multitenancy is deliberately small: it finds the current tenant, runs configurable tasks when the tenant switches, and can make queued jobs tenant aware.

I built this platform’s tenancy by hand because the shared-database version is small, a handful of classes plus their tests, and I wanted every rule to fail closed and every opt-out to be visible. That trade-off changes with the tenancy model:

08Where to go next

Once requests are safely inside one tenant, the next questions are what each user may do and which records they see; multi-tenant access control covers that in Laravel with Spatie’s laravel-permission. If you already run a Laravel platform and want an outside check of its tenancy, the Platform Change-Readiness Scorecard scores tenant isolation in about ten minutes, and a SaaS architecture review goes through the code.