Choose a multi-tenant architecture based on isolation and scalability needs; 2. Identify tenants via subdomain or domain using middleware to resolve and store the current tenant; 3. Configure dynamic database connections by setting tenant-specific database configurations at runtime and assigning them to models; 4. Automate database provisioning by creating a new database and running migrations when a tenant registers; 5. Organize tenant-specific migrations in a dedicated folder and use a base model with the tenant connection; 6. Secure data access by enforcing connection usage, avoiding global cache leaks, and applying policies; 7. Handle queue jobs and scheduled tasks by re-resolving the tenant context within jobs to maintain data isolation; 8. Optionally, use Spatie Laravel Multitenancy package to simplify tenant management, including automatic context switching and queue isolation; always test thoroughly, avoid trusting user input, use scoped caching, separate filesystem disks, and isolated test environments to ensure robustness and security of the multi-tenant application.

Building a multi-tenant application in Laravel means serving multiple clients (tenants) from a single codebase, each with isolated data. There are different approaches—single database with tenant identifiers, separate databases per tenant, or schema-based isolation. The choice depends on your scalability, security, and maintenance needs.

Here’s how to build a solid multi-tenant app in Laravel using a common and scalable approach: one database per tenant with dynamic database connections.

1. Choose Your Multi-Tenant Architecture

Before coding, decide on your tenancy model:

• Single Database (Row-level isolation)
  All tenants share one database; data is separated by a tenant_id column.
  ? Simple to manage
  ? Risk of data leakage if queries aren’t scoped properly

• Multiple Databases (Per tenant)
  Each tenant has their own database.
  ? Strong data isolation
  ? More complex setup and backup strategy

  

• PostgreSQL Schemas (Hybrid)
  One database, but each tenant gets its own schema.
  ? Good balance of isolation and manageability
  ? Limited to PostgreSQL

For this guide, we’ll use multiple databases (one per tenant), which is ideal for SaaS apps needing strong separation.

2. Set Up Tenant Identification

You need to identify the tenant on every request—usually via subdomain or domain.

Example: Identify Tenant by Subdomain

// Middleware: ResolveTenant.php
public function handle($request, Closure $next)
{
    $host = $request->getHost(); // tenant1.yourapp.com
    $subdomain = explode('.', $host)[0];

    $tenant = Tenant::where('subdomain', $subdomain)->first();

    if (! $tenant) {
        abort(404, 'Tenant not found');
    }

    // Store tenant in request or use a global accessor
    app()->instance('currentTenant', $tenant);

    return $next($request);
}

Register this middleware in app/Http/Kernel.php as a global or route middleware.

3. Configure Dynamic Database Connections

Laravel allows runtime database connection switching.

Add Dynamic Connection

In your middleware or service provider:

Config::set("database.connections.tenant", [
    'driver' => 'mysql',
    'host' => $tenant->db_host,
    'database' => $tenant->db_name,
    'username' => $tenant->db_username,
    'password' => $tenant->db_password,
    // ... other options
]);

Then, use it:

DB::connection('tenant')->table('users')->get();

Or set Eloquent models to use it:

class Customer extends Model
{
    protected $connection = 'tenant';
}

4. Automate Database Provisioning

When a new tenant signs up, create their database and run migrations.

// In tenant registration logic
$tenant = new Tenant([
    'name' => $request->name,
    'subdomain' => $request->subdomain,
    // database credentials or generate them
]);
$tenant->save();

// Create database
DB::statement("CREATE DATABASE {$tenant->db_name}");

// Configure connection
Config::set('database.connections.tenant', $this->getConnectionConfig($tenant));

// Run migrations
Artisan::call('migrate', [
    '--database' => 'tenant',
    '--path' => 'database/migrations/tenant'
]);

? Use a service class to encapsulate tenant setup logic.

5. Organize Tenant-Specific Migrations and Models

Keep tenant-specific migrations separate:

/database/migrations/tenant/
    create_customers_table.php
    create_invoices_table.php

Use a base model for tenant models:

abstract class TenantModel extends Model
{
    protected $connection = 'tenant';
}

6. Secure Data Access

Always ensure models and queries use the correct connection. Never mix tenant and system data.

• Use middleware to resolve tenant early.
• Avoid caching tenant data globally unless scoped.
• Use policies and scopes to prevent accidental access.

7. Handle Queue Jobs and Scheduled Tasks

When using queues or schedule:run, Laravel may lose tenant context. You must re-resolve the tenant.

For queued jobs:

class ProcessInvoice
{
    protected $tenant;

    public function __construct($tenant, $data)
    {
        $this->tenant = $tenant;
        $this->data = $data;
    }

    public function handle()
    {
        // Reconnect to tenant DB
        Config::set('database.connections.tenant', $this->tenant->dbConfig());
        DB::setDefaultConnection('tenant');

        // Now proceed
    }
}

Or use packages like Spatie Laravel-Multitenancy to automate context preservation.

8. (Optional) Use a Package

Instead of building from scratch, consider:

• Spatie Laravel Multitenancy
  Handles tenant switching, jobs, caching, and more. Highly recommended.

With Spatie:

// Auto-switch tenant
$tenant->makeCurrent();

// Everything from here uses tenant DB
User::all(); // from tenant DB

// Switch back
$tenant->forgetCurrent();

It also supports teams, domains, and queue isolation.

Final Tips

• ? Test thoroughly—especially tenant switching and fallbacks.
• ? Never trust user input for tenant resolution.
• ? Use database seeds for tenant onboarding.
• ? Consider using separate filesystem disks per tenant (e.g., S3 prefixes).
• ? Run tests in isolation (e.g., use separate test databases).

Basically, building multi-tenant Laravel apps is manageable once you isolate tenant resolution, database switching, and provisioning. Start simple, then scale with tools like Spatie’s package when needed.

The above is the detailed content of How to build a multi-tenant application in Laravel?. For more information, please follow other related articles on the PHP Chinese website!