Implementing Multi-Tenancy: Architecting Isolated Laravel Applications

Previously in this course, we explored testing with test doubles to isolate our logic from external dependencies. In this lesson, we shift our focus to architectural isolation: implementing multi-tenancy.

Multi-tenancy is the architectural backbone of any SaaS application. It allows a single instance of your software to serve multiple customers (tenants), each with their own isolated data. Failing to design for this from the ground up often leads to "leaky" data, where a user from Tenant A accidentally views or modifies data belonging to Tenant B.

Designing for Multi-Tenancy

When architecting for multi-tenancy, your primary goal is data isolation. You must decide how to partition the data before writing your first migration. There are three common approaches:

For most Laravel applications, the Column-based approach is the standard starting point. It is cost-effective, easy to back up, and works seamlessly with standard Eloquent relationships. We will focus on this pattern, as it forces us to be explicit about our query scoping.

Implementing Tenant Scoping

To implement column-based multi-tenancy, every model related to a tenant (like our Project or Task models) must include a tenant_id column. The challenge is ensuring that every query automatically filters by this ID without manually adding ->where('tenant_id', ...) everywhere.

We achieve this using Global Scopes.

Step 1: The Tenant Trait

Create a BelongsToTenant trait that automatically applies a scope to any model using it.

PHP
namespace App\Traits;

use App\Models\Scopes\TenantScope;
use Illuminate\Support\Facades\Auth;

trait BelongsToTenant
{
    protected static function bootBelongsToTenant()
    {
        static::addGlobalScope(new TenantScope);

        static::creating(function ($model) {
            if (Auth::check()) {
                $model->tenant_id = Auth::user()->tenant_id;
            }
        });
    }
}

Step 2: The Global Scope

The TenantScope class intercepts the query builder to inject the constraint.

PHP
namespace App\Models\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;
use Illuminate\Support\Facades\Auth;

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        if (Auth::check()) {
            $builder->where('tenant_id', Auth::user()->tenant_id);
        }
    }
}

Managing Data Isolation

Even with global scopes, you must be vigilant. A common risk is the "Context Switch" problem—where a background job or an API command runs without a logged-in user, potentially returning empty results or, worse, all results if you aren't careful.

When dealing with API architecture and request context propagation, always ensure the tenant_id is explicitly set in the container or via a service class, rather than relying solely on Auth::user().

The Project Board Evolution

In our project board application, we now need to ensure every Project is tied to a tenant_id.

1. Migration: Add unsignedBigInteger('tenant_id')->index() to your projects and tasks tables.
2. Model: Apply the BelongsToTenant trait to the Project and Task models.
3. Controller: Because we use global scopes, your index methods like Project::all() will now automatically return only the projects belonging to the authenticated user's tenant.

Hands-on Exercise

1. Create a Tenant model and a migration that adds tenant_id to your existing users, projects, and tasks tables.
2. Implement the BelongsToTenant trait as shown above.
3. Write a feature test that attempts to access a project belonging to a different tenant_id. Assert that a 404 Not Found or 403 Forbidden response is returned, proving the scope is working.

Common Pitfalls

• Forgetting Global Scopes in Jobs: If you dispatch a background job, the Auth::user() will be null. You must pass the tenant_id into the job constructor and manually set it in the job's handle() method.
• Seeding/Testing: When running tests, global scopes will hide data from your factories. Use withoutGlobalScope(TenantScope::class) when verifying data in your test assertions.
• The "Cross-Tenant" Leak: Never assume that an ID is globally unique. Always validate that the requested resource belongs to the current tenant before performing an update or delete.

Recap

Multi-tenancy requires a strict adherence to data isolation. By leveraging Global Scopes, we ensure that our application logic is "tenant-aware" by default. While this approach simplifies development, always remember that background processes and console commands require explicit tenant context to prevent data leaks.

Up next: We will discuss Refactoring Legacy Code to ensure our growing codebase remains maintainable as we add features.