stancl/tenancy

Overview of Multi-Tenancy Models Multi-tenancy allows a single application to serve multiple distinct groups of users, or tenants, while keeping their data invisible to one another. In the Laravel ecosystem, this architecture usually takes two forms: **single-database** and **multi-database** isolation. Choosing between them depends on your scale, legal requirements, and the nature of your customers. For B2C apps where users are individuals, a shared database with simple filtering is often sufficient. However, for B2B enterprises requiring strict data privacy, physically separating data into different databases is the standard. Prerequisites To follow this guide, you should be comfortable with PHP and the Laravel framework. Familiarity with Eloquent models, Middleware, and Artisan commands is essential. You should also understand basic DNS concepts like wildcards and subdomains if you plan to implement database-per-tenant isolation. Key Libraries & Tools * **stancl/tenancy**: A powerful package (also known as Tenancy for Laravel) that automates database creation, switching, and routing for multi-tenant apps. * **Laravel Fortify**: A front-end agnostic authentication backend used to handle registration and login logic. * **Laravel Herd**: A local development environment that simplifies managing subdomains and local testing. Code Walkthrough: Implementing Logic 1. Single Database Filtering In a shared database, you typically include an `organization_id` on every table. You can then use Eloquent scopes to ensure users only see their own data. ```php // TaskController.php public function store(Request $request) { // Automatically associate task with the user's organization $task = Task::create([ 'title' => $request->title, 'user_id' => auth()->id(), 'organization_id' => auth()->user()->organization_id, ]); } ``` 2. Multi-Database Setup with stancl/tenancy When using stancl/tenancy, the package handles the heavy lifting of switching database connections based on the current subdomain. You must define a `Tenant` model to track these entities. ```php // config/tenancy.php 'tenant_model' => App\Models\Tenant::class, // Creating a tenant during registration $tenant = Tenant::create(['id' => $subdomain]); $tenant->domains()->create(['domain' => $subdomain . '.yourapp.test']); ``` Syntax Notes & Authentication Pitfalls Modern Laravel starter kits often use Laravel Fortify, which abstracts routes into internal actions. When implementing subdomains, you must override the `LogoutResponse` and `LoginResponse` to ensure users are redirected to the correct tenant-specific URL. Without these overrides, the application might attempt to authenticate a user against the central database rather than the tenant-specific database, leading to failed logins. Tips & Gotchas When scaling a multi-database architecture, remember that you cannot easily perform cross-database joins. If your users are stored in the central database but tasks are in tenant databases, standard Eloquent relationships will fail. Furthermore, always use `tenants:migrate` instead of the standard migration command to ensure every tenant schema stays in sync. If one tenant grows massively, you may eventually need to move their specific database to a dedicated server, a process that requires robust DevOps orchestration.