Multi-Tenant SaaS with Laravel 12: A Production Architecture Guide

Almost every B2B Laravel app eventually grows into a multi-tenant SaaS. The decisions you make in the first month single database vs database-per-tenant, subdomain vs path-based routing, how you scope queries are very expensive to undo at month twelve. This guide is an opinionated walkthrough of the architecture I would pick for a new SaaS in 2026.

1. The schema decision

-- 0001_create_workspaces_table.php
CREATE TABLE workspaces (
    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
    slug VARCHAR(60) UNIQUE NOT NULL,
    name VARCHAR(120) NOT NULL,
    plan VARCHAR(40) DEFAULT 'free',
    trial_ends_at TIMESTAMP NULL,
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL
);

-- Every tenant-scoped table gets this:
ALTER TABLE projects ADD COLUMN workspace_id BIGINT UNSIGNED NOT NULL AFTER id;
ALTER TABLE projects ADD INDEX idx_workspace (workspace_id);
ALTER TABLE projects ADD CONSTRAINT fk_projects_workspace
    FOREIGN KEY (workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE;

2. The tenancy primitive

// app/Models/Workspace.php
class Workspace extends Model
{
    protected $fillable = ['slug', 'name', 'plan', 'trial_ends_at'];
    protected $casts = ['trial_ends_at' => 'datetime'];

    public function users()    { return $this->belongsToMany(User::class)->withPivot('role'); }
    public function projects() { return $this->hasMany(Project::class); }
    public function owner()    { return $this->users()->wherePivot('role', 'owner'); }

    public static function current(): ?self { return app('current.workspace'); }
}

// app/Http/Middleware/ResolveWorkspace.php
class ResolveWorkspace
{
    public function handle(Request $request, Closure $next)
    {
        $host = $request->getHost();
        $rootDomain = config('app.root_domain');

        $slug = Str::endsWith($host, '.' . $rootDomain)
            ? Str::before($host, '.' . $rootDomain)
            : $request->route('workspace');

        $workspace = Workspace::where('slug', $slug)->firstOrFail();

        abort_unless($workspace->users->contains($request->user()), 403);

        app()->instance('current.workspace', $workspace);
        URL::defaults(['workspace' => $workspace->slug]);

        return $next($request);
    }
}

3. The global scope you cannot forget

// app/Models/Concerns/BelongsToWorkspace.php
trait BelongsToWorkspace
{
    protected static function bootBelongsToWorkspace(): void
    {
        static::addGlobalScope('workspace', function (Builder $query) {
            if ($workspace = Workspace::current()) {
                $query->where($query->getModel()->getTable() . '.workspace_id', $workspace->id);
            }
        });

        static::creating(function ($model) {
            if (! $model->workspace_id && $workspace = Workspace::current()) {
                $model->workspace_id = $workspace->id;
            }
        });
    }

    public function workspace() { return $this->belongsTo(Workspace::class); }
}

4. Tenant-aware queues

Jobs run outside the request lifecycle. Workspace::current() returns null inside a queued job unless you teach it the tenant.

abstract class TenantAwareJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $workspaceId;

    public function __construct()
    {
        $this->workspaceId = Workspace::current()?->id
            ?? throw new RuntimeException('TenantAwareJob dispatched outside a workspace context');
    }

    public function handle(): void
    {
        $workspace = Workspace::findOrFail($this->workspaceId);
        app()->instance('current.workspace', $workspace);
        $this->run();
    }

    abstract protected function run(): void;
}

// Every job extends this — no exceptions.
class GenerateMonthlyReport extends TenantAwareJob
{
    protected function run(): void
    {
        $report = Report::create([...]);
        // Project::query() now scopes to the right workspace automatically.
    }
}

5. Stripe Cashier per workspace

// app/Models/Workspace.php
use Laravel\Cashier\Billable;

class Workspace extends Model
{
    use Billable;

    public function stripeName(): string { return $this->name; }
    public function stripeEmail(): string { return $this->owner->first()->email; }
}

// Subscribing
$workspace->newSubscription('default', 'price_pro_monthly')
          ->trialDays(14)
          ->create($paymentMethodId);

// Gating features
public function handle(Request $request, Closure $next, string $feature)
{
    abort_unless(
        Workspace::current()->subscription('default')?->valid()
        && Workspace::current()->subscription('default')->hasProduct($feature),
        402
    );
    return $next($request);
}

6. The ops checklist nobody talks about

When to bail to DB-per-tenant

Final word

Multi-tenancy is not a Laravel feature you install — it is an architecture you commit to. Get the schema, the global scope, the tenant-aware jobs, and the test discipline right early, and the next three years of feature work compound on a foundation that does not leak. Get any of those wrong, and the cleanup will dominate your roadmap.