Multi-tenancy and SaaS: one app, many centres

tenancy/app/Scopes/TenantScope.php

<?php

namespace App\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;
use Illuminate\Support\Facades\Context;
use RuntimeException;

class TenantScope implements Scope
{
    /**
     * Adds "where <table>.centre_id = <current centre>" to every Eloquent query of the model.
     */
    public function apply(Builder $builder, Model $model): void
    {
        // Fail closed: with no centre known, refuse the query instead of reading every centre's rows.
        $centreId = Context::get('centre_id')
            ?? throw new RuntimeException('No centre is set for a query on '.$model->getTable());

        // Qualified with the table name, so a join with another table that has centre_id stays unambiguous.
        $builder->where($model->qualifyColumn('centre_id'), $centreId);
    }
}

tenancy/app/Models/Student.php

<?php

namespace App\Models;

use App\Models\Concerns\BelongsToCentre;
use App\Scopes\TenantScope;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\ScopedBy;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

#[Fillable(['name'])]
#[ScopedBy(TenantScope::class)]
class Student extends Model
{
    use BelongsToCentre;

    public function instalments(): HasMany
    {
        return $this->hasMany(Instalment::class);
    }
}

tenancy/app/Models/Concerns/BelongsToCentre.php

<?php

namespace App\Models\Concerns;

use App\Models\Centre;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Support\Facades\Context;
use RuntimeException;

trait BelongsToCentre
{
    /**
     * A new row always takes the current centre, so no controller can forget it or set another centre's id.
     */
    public static function bootBelongsToCentre(): void
    {
        static::creating(function (Model $model) {
            $model->centre_id = Context::get('centre_id')
                ?? throw new RuntimeException('No centre is set for a new row in '.$model->getTable());
        });
    }

    public function centre(): BelongsTo
    {
        return $this->belongsTo(Centre::class);
    }
}

the migration · tenancy/database/migrations/2026_01_15_000001_create_centres_table.php

<?php

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

return new class extends Migration
{
    /**
     * One database for every centre: each tenant-owned table carries centre_id.
     */
    public function up(): void
    {
        Schema::create('centres', function (Blueprint $table) {
            $table->id();
            $table->string('slug')->unique();   // the subdomain: north.pathshala.test
            $table->string('name');
            $table->string('plan')->default('starter');
            $table->timestamps();
        });

        // A clerk works at one centre.
        Schema::table('users', function (Blueprint $table) {
            $table->foreignId('centre_id')->nullable();
        });

        Schema::create('students', function (Blueprint $table) {
            $table->id();
            $table->foreignId('centre_id')->constrained();
            $table->string('name');
            $table->timestamps();
            $table->index(['centre_id', 'name']);
        });

        Schema::create('instalments', function (Blueprint $table) {
            $table->id();
            $table->foreignId('centre_id')->constrained();
            $table->foreignId('student_id')->constrained();
            $table->unsignedInteger('amount_paise');
            $table->timestamp('paid_at')->nullable();
            $table->timestamps();
            $table->index(['centre_id', 'paid_at']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('instalments');
        Schema::dropIfExists('students');
        Schema::table('users', fn (Blueprint $table) => $table->dropColumn('centre_id'));
        Schema::dropIfExists('centres');
    }
};

tenancy/database/seeders/CentreSeeder.php

<?php

namespace Database\Seeders;

use App\Models\Centre;
use App\Models\Student;
use App\Models\User;
use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\Context;

class CentreSeeder extends Seeder
{
    public function run(): void
    {
        $north = Centre::create(['slug' => 'north', 'name' => 'Pathshala North', 'plan' => 'scale']);
        $south = Centre::create(['slug' => 'south', 'name' => 'Pathshala South', 'plan' => 'starter']);

        User::factory()->create(['name' => 'Asha', 'email' => 'asha@north.example', 'centre_id' => $north->id]);
        User::factory()->create(['name' => 'Ravi', 'email' => 'ravi@south.example', 'centre_id' => $south->id]);

        // [name, unpaid instalment in paise or null]: each centre's rows are written inside its own context.
        $this->students($north, [['Aarav Shah', null], ['Diya Rao', 450000], ['Kabir Iyer', 300000]]);
        $this->students($south, [['Meera Nair', 250000], ['Rohan Das', null]]);
    }

    private function students(Centre $centre, array $rows): void
    {
        Context::scope(function () use ($rows) {
            foreach ($rows as [$name, $unpaid]) {
                $student = Student::create(['name' => $name]);
                $student->instalments()->create([
                    'amount_paise' => $unpaid ?? 450000,
                    'paid_at' => $unpaid === null ? now() : null,
                ]);
            }
        }, ['centre_id' => $centre->id]);
    }
}

routes/console.php · tenancy/routes/console.php

<?php

use App\Models\Centre;
use App\Models\Student;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Context;

// A command runs outside any request, so no centre is set until the command sets one.
Artisan::command('students:count {centre?}', function (?string $centre = null) {
    try {
        $count = $centre === null
            ? Student::count()
            : Context::scope(fn () => Student::count(), ['centre_id' => Centre::where('slug', $centre)->value('id')]);
        $this->line('students: '.$count);
    } catch (RuntimeException $e) {
        $this->error($e->getMessage());

        return 1;
    }
});

// The SQL of one query on the scoped model, as the database receives it.
Artisan::command('students:sql {centre}', function (string $centre) {
    $sql = Context::scope(
        fn () => Student::orderBy('name')->toRawSql(),
        ['centre_id' => Centre::where('slug', $centre)->value('id')],
    );
    $this->line($sql);
});

routes/web.php · tenancy/routes/web.php

<?php

use App\Http\Middleware\ResolveCentre;
use App\Models\Student;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/', fn () => view('welcome'));

// Every centre's pages: {centre} is the first label of the host, north in north.pathshala.test.
Route::domain('{centre}.pathshala.test')->middleware(ResolveCentre::class)->group(function () {
    Route::get('/students', fn () => [
        'students' => Student::orderBy('name')->pluck('name'),
        'first' => route('students.show', Student::orderBy('id')->first()),
    ])->name('students.index');

    // Route model binding runs the scoped query, so another centre's id is simply not found.
    Route::get('/students/{student}', fn (Student $student) => $student->only('id', 'name'))
        ->name('students.show');

    Route::post('/students', fn (Request $request) => Student::create(
        $request->validate(['name' => ['required', 'string', 'max:80']])
    ))->name('students.store');
});

tenancy/app/Http/Middleware/ResolveCentre.php

<?php

namespace App\Http\Middleware;

use App\Models\Centre;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Context;
use Illuminate\Support\Facades\URL;
use Symfony\Component\HttpFoundation\Response;

class ResolveCentre
{
    /**
     * Finds the centre named by the subdomain and makes it the current centre for this request.
     */
    public function handle(Request $request, Closure $next): Response
    {
        $centre = Centre::where('slug', $request->route('centre'))->first();

        // An unknown centre and a user of another centre get the same answer: not found.
        abort_if($centre === null || $request->user()?->centre_id !== $centre->id, 404);

        Context::add('centre_id', $centre->id);        // read by TenantScope, log lines and queued jobs
        URL::defaults(['centre' => $centre->slug]);     // route() keeps generated links on this subdomain
        $request->route()->forgetParameter('centre');   // route actions do not receive it as an argument

        return $next($request);
    }
}

bootstrap/app.php · tenancy/bootstrap/app.php

<?php

use App\Http\Middleware\ResolveCentre;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;
use Illuminate\Routing\Middleware\ThrottleRequests;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        // The centre must be known before rate limiting and route model binding run (both come later).
        $middleware->prependToPriorityList(before: ThrottleRequests::class, prepend: ResolveCentre::class);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->shouldRenderJsonWhen(
            fn (Request $request) => $request->is('api/*') || $request->expectsJson(),
        );
    })->create();

tenancy/request.php

<?php

/*
 * Sends one request through the app, as a browser signed in on that host would, and prints the status and the body.
 *   php request.php [--as=<email>] [--post] [--sql] <url>
 * --as signs that user in first, --post sends a POST from the same origin, --sql prints the SQL the request ran.
 * One request per run, like one request per PHP process on a server.
 */

use App\Models\User;
use Illuminate\Contracts\Http\Kernel;
use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;

require __DIR__.'/vendor/autoload.php';
$app = require __DIR__.'/bootstrap/app.php';
$kernel = $app->make(Kernel::class);
$kernel->bootstrap();

$options = getopt('', ['as:', 'post', 'sql'], $rest);
$request = Request::create($argv[$rest], isset($options['post']) ? 'POST' : 'GET', server: [
    'HTTP_ACCEPT' => 'application/json',
    'HTTP_SEC_FETCH_SITE' => 'same-origin',
]);
$app->instance('request', $request);

if (isset($options['as'])) {
    $app['auth']->guard('web')->setUser(User::where('email', $options['as'])->firstOrFail());
}

$queries = [];
if (isset($options['sql'])) {
    DB::listen(function (QueryExecuted $query) use (&$queries) {
        if (! str_contains($query->sql, '"sessions"') && ! str_contains($query->sql, '"cache')) {
            $queries[] = $query->toRawSql();
        }
    });
}

$response = $kernel->handle($request);

$status = $response->getStatusCode();
$json = json_decode($response->getContent());
$shown = $status < 400 ? json_encode($json, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE) : ($json->message ?? '');
echo $status.' '.$shown.PHP_EOL;
foreach ($queries as $sql) {
    echo 'sql: '.$sql.PHP_EOL;
}

$kernel->terminate($request, $response);