Multi-Tenancy Overview

class Tenant extends Model
{
    use HasFactory;
    use HasUuids;
    use SoftDeletes;

    protected $keyType = 'string';
    public $incrementing = false;

    protected $fillable = [
        'name',
        'slug',
        'owner_id',
        'settings',
        'legal_name',
        'address',
        'city',
        'postal_code',
        'country',
        'vat_number',
        'billing_email',
        'preferred_currency',
        'stripe_customer_id',
        'onboarding_completed_at',
    ];

    protected function casts(): array
    {
        return [
            'settings' => 'array',
            'onboarding_completed_at' => 'datetime',
        ];
    }

    public function newUniqueId(): string
    {
        return (string) Str::orderedUuid();
    }
}

public function isOnboardingComplete(): bool
{
    return $this->onboarding_completed_at !== null;
}

public function hasActiveSubscription(): bool
{
    return $this->subscriptions()
        ->whereIn('status', [SubscriptionStatus::Active, SubscriptionStatus::Trialing])
        ->exists();
}

public function hasBillingDetails(): bool
{
    return $this->legal_name !== null
        && $this->address !== null
        && $this->city !== null
        && $this->postal_code !== null
        && $this->country !== null
        && $this->billing_email !== null;
}

public function billingContactEmail(): ?string
{
    return $this->billing_email ?? $this->owner?->email;
}

public function markOnboardingComplete(): void
{
    $this->update(['onboarding_completed_at' => now()]);
}

// All tenants this user belongs to
public function tenants(): BelongsToMany
{
    return $this->belongsToMany(Tenant::class)
        ->withPivot('joined_at')
        ->withTimestamps();
}

// Tenants this user owns (created)
public function ownedTenants(): HasMany
{
    return $this->hasMany(Tenant::class, 'owner_id');
}

// Check membership in a specific tenant
public function belongsToTenant(Tenant $tenant): bool
{
    return $this->tenants()->where('tenant_id', $tenant->id)->exists();
}

// The user who created this tenant
public function owner(): BelongsTo
{
    return $this->belongsTo(User::class, 'owner_id');
}

// All users who belong to this tenant
public function users(): BelongsToMany
{
    return $this->belongsToMany(User::class)
        ->withPivot('joined_at')
        ->withTimestamps();
}

final class TenantContext
{
    private ?Tenant $tenant = null;

    public function set(?Tenant $tenant): void
    {
        $this->tenant = $tenant;
    }

    public function get(): ?Tenant
    {
        return $this->tenant;
    }

    public function id(): ?string
    {
        return $this->tenant?->id;
    }

    public function has(): bool
    {
        return $this->tenant !== null;
    }

    public function clear(): void
    {
        $this->tenant = null;
    }
}

function current_tenant(): ?Tenant
{
    return app(TenantContext::class)->get();
}

function current_tenant_id(): ?string
{
    return app(TenantContext::class)->id();
}

function set_current_tenant(?Tenant $tenant): void
{
    app(TenantContext::class)->set($tenant);
}

function has_tenant(): bool
{
    return app(TenantContext::class)->has();
}

$middleware->alias([
    'tenant.resolve'     => ResolveTenant::class,
    'tenant.member'      => EnsureTenantMember::class,
    'onboarding.complete' => EnsureOnboardingComplete::class,
    // ...
]);

// Layer 1: Auth + tenant resolution
Route::middleware(['auth:sanctum', 'tenant.resolve'])->group(function () {

    // Layer 2: Membership + onboarding enforcement
    Route::middleware(['tenant.member', 'onboarding.complete'])->group(function () {
        Route::get('/tenant', [TenantController::class, 'show']);
        Route::patch('/tenant', [TenantController::class, 'update']);
    });

    // Tenant-scoped routes with explicit tenant ID in URL
    Route::prefix('tenant/{tenantId}')
        ->middleware(['tenant.member', 'onboarding.complete'])
        ->group(function () {
            Route::get('invoices', [InvoiceController::class, 'index']);
            Route::get('subscription', [SubscriptionController::class, 'show']);
            // ...
        });
});