How to build a multi-tenant SaaS in Laravel (step by step)

This guide uses single database + tenant_id. For database-per-tenant, look at a package such as stancl/tenancy.

1. 1

   PHP 8.2+ and Composer

   Check the PHP version your Laravel release requires.

2. 2

   A database

   MySQL or PostgreSQL.

3. 3

   Stripe test account

   For the test-mode keys.

4. 4

   Local subdomains

   Laravel Herd/Valet, or entries in your hosts file.

composer create-project laravel/laravel saas
cd saas
php artisan make:model Tenant -m

// database/migrations/xxxx_create_tenants_table.php
Schema::create('tenants', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('subdomain')->unique();
    $table->timestamps();
});

// add to the users migration (and every tenant-owned table)
$table->foreignId('tenant_id')->constrained()->cascadeOnDelete();

php artisan make:middleware IdentifyTenant

// app/Http/Middleware/IdentifyTenant.php
public function handle(Request $request, Closure $next): Response
{
    $sub = explode('.', $request->getHost())[0];
    $tenant = Tenant::where('subdomain', $sub)->firstOrFail();

    app()->instance(Tenant::class, $tenant);

    return $next($request);
}

// routes/web.php
Route::domain('{tenant}.' . config('app.domain'))
    ->middleware(['web', IdentifyTenant::class])
    ->group(function () {
        Route::get('/', DashboardController::class);
    });

Add 'domain' => env('APP_DOMAIN') to config/app.php and set APP_DOMAIN=yourapp.test.

// app/Models/Concerns/BelongsToTenant.php
trait BelongsToTenant
{
    protected static function bootBelongsToTenant(): void
    {
        static::addGlobalScope('tenant', function (Builder $query) {
            if (app()->bound(Tenant::class)) {
                $query->where($query->getModel()->getTable() . '.tenant_id', app(Tenant::class)->id);
            }
        });

        static::creating(function (Model $model) {
            if (app()->bound(Tenant::class) && ! $model->tenant_id) {
                $model->tenant_id = app(Tenant::class)->id;
            }
        });
    }
}

Add use BelongsToTenant; to every tenant-owned model (Project, Invoice...).

public function __construct(public int $tenantId) {}

public function handle(): void
{
    app()->instance(Tenant::class, Tenant::findOrFail($this->tenantId));
    // ... tenant-scoped work
}

composer require laravel/cashier
php artisan vendor:publish --tag="cashier-migrations"
php artisan migrate

// The tenant pays, not the user:
use Laravel\Cashier\Billable;
class Tenant extends Model { use Billable; }

// app/Providers/AppServiceProvider.php -> boot()
Cashier::useCustomerModel(Tenant::class);

The published migrations target users; edit them to add the billing columns to tenants and point subscriptions at the tenant before migrating.

// start a subscription (Stripe Checkout)
return $tenant->newSubscription('default', 'price_XXXX')
    ->checkout(['success_url' => route('billing.done'), 'cancel_url' => route('billing')]);

Put STRIPE_KEY, STRIPE_SECRET and STRIPE_WEBHOOK_SECRET in .env and register the webhook at /stripe/webhook.

// tests/Feature/TenantIsolationTest.php (Pest)
it('never shows another tenant\'s projects', function () {
    $acme = Tenant::factory()->create(['subdomain' => 'acme']);
    $globex = Tenant::factory()->create(['subdomain' => 'globex']);
    Project::factory()->for($globex)->create(['name' => 'Secret']);

    app()->instance(Tenant::class, $acme);

    expect(Project::count())->toBe(0);
});

Write one of these for every tenant-owned model. It's the cheapest insurance you'll ever buy.

1. Raw queries skip scopes

   DB::table() ignores global scopes; add where tenant_id yourself.

2. Unique columns

   Make them unique per tenant: unique([tenant_id, email]).

3. Cache key collisions

   Prefix cache keys with the tenant id.

4. Route model binding

   Scoped models 404 on other tenants; test it.

1. Tenant resolved from subdomain

   Unknown subdomains return 404.

2. Every tenant table has tenant_id

   And uses BelongsToTenant.

3. Billing on the tenant

   Webhook registered and tested.

4. Isolation tests in CI

   They run on every push.