Building a Multi-Tenancy Application in Laravel 13

What You'll Build

In this tutorial, you'll create a multi-tenancy application using Laravel 13. The application will support multiple tenants, each with its own isolated data. By the end, you'll have a working project where users from different organizations can log in and interact with their own data without interfering with each other.

Why This Matters

Multi-tenancy is a crucial architectural pattern for SaaS applications where multiple customers (tenants) share the same application but have isolated data. This pattern is beneficial when:

• You are developing a SaaS product: Multi-tenancy allows you to serve multiple clients with a single instance of your application, reducing infrastructure costs.
• Data isolation is required: Each tenant's data is separate, ensuring privacy and security.
• Scalability is a concern: You can scale the application more efficiently by managing resources for all tenants from a centralized system.

Developers and companies building SaaS products will benefit significantly from understanding and implementing multi-tenancy, as it optimizes resource usage and simplifies maintenance.

Architecture Overview

In a multi-tenancy setup, you typically have two main approaches:

1. Database-per-tenant: Each tenant has its own database. This provides strong isolation but can be more complex to manage.
2. Single Database, Shared Schema: All tenants share the same database and tables, with tenant data differentiated by a tenant identifier.

For this tutorial, we'll focus on the shared schema approach, which is simpler to implement and manage for small to medium-sized applications.

Here's a simplified architecture diagram:

+-------------------+
|   Application     |
|   (Laravel 13)    |
+-------------------+
         |
         v
+-------------------+
|   Tenant Manager  |
+-------------------+
         |
         v
+-------------------+
|   Shared Database |
+-------------------+
|   Tenant Data     |
|   Tenant Data     |
|   Tenant Data     |
+-------------------+

Step-by-Step Implementation

Let's walk through the steps to build this application.

Step 1: Set Up a New Laravel Project

First, we need to create a new Laravel project. Ensure you have Composer installed on your system.

Run the following command to create a new Laravel project:

composer create-project --prefer-dist laravel/laravel multitenancy-app

Navigate into your project directory:

cd multitenancy-app

This command sets up a new Laravel project, which will serve as the foundation for our multi-tenancy application.

Step 2: Configure the Database

Next, we'll set up the database. For our shared schema approach, we'll use a single database for all tenants.

1. Create a new database in your database management system (e.g., MySQL, PostgreSQL).
2. Update your .env file with the database credentials:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=multitenancy
DB_USERNAME=root
DB_PASSWORD=secret

3. Run the following command to generate the Laravel application key:

php artisan key:generate

This step ensures your application can connect to the database and has a unique encryption key.

Step 3: Create Tenant and User Models

We need models to represent tenants and users. We'll use Laravel's Eloquent ORM to create these models.

1. Create a migration for the tenants table:

php artisan make:migration create_tenants_table

Edit the generated migration file in database/migrations:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('tenants', function (Blueprint $table) {
            $table->id();
            $table->string('name')->unique();
            $table->string('domain')->unique();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('tenants');
    }
};

2. Create a migration for the users table:

php artisan make:migration create_users_table

Edit the generated migration file:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {
            $table->id();
            $table->foreignId('tenant_id')->constrained()->onDelete('cascade');
            $table->string('name');
            $table->string('email')->unique();
            $table->string('password');
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

3. Run the migrations to create the tables:

php artisan migrate

These steps set up the basic database structure with tenants and users tables, allowing us to store tenant-specific user data.

Step 4: Set Up Tenant Identification Middleware

To ensure that each request is handled in the context of the correct tenant, we'll set up middleware to identify the tenant based on the incoming request. This is crucial for ensuring data isolation.

1. Create a new middleware:

php artisan make:middleware IdentifyTenant

2. Edit the newly created middleware file at app/Http/Middleware/IdentifyTenant.php:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use App\Models\Tenant;

class IdentifyTenant
{
    public function handle(Request $request, Closure $next)
    {
        $host = $request->getHost();
        $tenant = Tenant::where('domain', $host)->first();

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

        // Store tenant in the request for later use
        $request->attributes->set('tenant', $tenant);

        return $next($request);
    }
}

3. Register the middleware in app/Http/Kernel.php:

protected $middlewareGroups = [
    'web' => [
        // other middleware
        \App\Http\Middleware\IdentifyTenant::class,
    ],
];

This middleware checks the domain of the incoming request and loads the corresponding tenant, aborting the request if no tenant is found.

Step 5: Implement Tenant-Specific Logic in Controllers

With the tenant identified, you can now implement tenant-specific logic in your controllers. Here's an example of how you might modify a controller to use tenant information:

1. Create a controller for managing some tenant-specific resource, e.g., Projects:

php artisan make:controller ProjectController

2. Edit app/Http/Controllers/ProjectController.php:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\Project;

class ProjectController extends Controller
{
    public function index(Request $request)
    {
        $tenant = $request->attributes->get('tenant');

        $projects = Project::where('tenant_id', $tenant->id)->get();

        return view('projects.index', compact('projects'));
    }

    // Other CRUD methods...
}

This setup ensures that each tenant only sees its own projects.

Step 6: Testing and Validation

1. Seed the database with test data for multiple tenants:

php artisan tinker

// Example seeding
$tenant1 = Tenant::create(['name' => 'Tenant One', 'domain' => 'tenant1.example.com']);
$tenant2 = Tenant::create(['name' => 'Tenant Two', 'domain' => 'tenant2.example.com']);

$tenant1->users()->create(['name' => 'User One', 'email' => 'user1@tenant1.com', 'password' => bcrypt('password')]);
$tenant2->users()->create(['name' => 'User Two', 'email' => 'user2@tenant2.com', 'password' => bcrypt('password')]);

2. Test your application by accessing different domains and ensuring data isolation.

Common Mistakes

• Middleware Not Registered: Forgetting to register the middleware can lead to tenants not being identified, resulting in data leakage.
• Database Configuration Errors: Ensure your .env file is correctly configured. Incorrect database credentials or settings can prevent your application from connecting to the database.
• Cache Issues: If you're using caching, ensure that tenant-specific data is cached with tenant-specific keys to avoid data overlap.

How I Would Use This

I would use this setup for small to medium SaaS applications where cost and simplicity are priorities. The shared schema approach is easier to manage but may not scale well for very large applications with thousands of tenants. For larger applications, a database-per-tenant approach might be more appropriate, despite its complexity.

Lessons Learned

• Tradeoffs: The shared schema approach is simpler but can become a bottleneck as the number of tenants grows. Always monitor performance.
• Unexpected Issues: Domain-based tenant identification can be tricky in local development environments. Consider using subdomains or local DNS for testing.
• Real-World Considerations: Ensure you have a robust logging and monitoring strategy to quickly identify and resolve tenant-specific issues.

Next Steps

• Explore More: Learn about database-per-tenant architecture and its implementation in Laravel.
• Security: Dive deeper into securing multi-tenant applications, focusing on data encryption and access control.
• Performance Optimization: Study caching strategies and query optimization techniques for multi-tenant applications.

Sources

• Laravel Documentation
• Multi-Tenancy in Laravel
• Eloquent ORM