laravel-multi-tenancy
Tenancy on stancl/tenancy v4. Middleware identifies the tenant, bootstrappers carry it into jobs, cache and storage, and central code is marked. Use only in a multi-tenant app, when writing tenant identification, central or tenant models, provisioning, or tenant tests.
How do I install this agent skill?
npx skills add https://github.com/leeovery/agentic-skills --skill laravel-multi-tenancyIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides architectural patterns and testing utilities for Laravel multi-tenant applications using the Stancl Tenancy package. It includes PHP snippets for actions, models, and test cases, all of which follow standard industry practices for multi-tenant software development.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- ZeroLeakspass
2 findings · Score: 80/100
What does this agent skill do?
Laravel Multi-Tenancy
In a multi-tenant app every line of code runs in one of two contexts: central (the app itself: tenants, plans, sign-up) or one tenant's. stancl/tenancy switches between them. Identification middleware finds the tenant on each request and initialises tenancy; bootstrappers then point the database, cache, filesystem and queue at that tenant, and revert them when tenancy ends. Tenant code is then ordinary Laravel code that never mentions the tenant. Central code is the marked exception, and the only code that moves between contexts.
This skill targets stancl/tenancy v4 (PHP 8.4, Laravel 12). v3 differs in namespaces and in how identification is configured; when composer.lock shows v3, check each API against its vendor source.
Choices the project makes once
| Choice | Options | Consequence |
|---|---|---|
| Where tenant data lives | A database per tenant, or one shared database | Decides how tenant models look (Rules, one shared database) |
| How a request names its tenant | Domain or subdomain, a path segment, or a header | Decides the middleware and what the tenant model needs (Identification) |
Follow the choice the project has made. Don't mix modes or identification methods without a reason the project states.
Rules
- Tenant code uses the normal layout; central code is marked. Central actions, DTOs and HTTP sit under a
Centrallevel (Actions/Central/Tenant/CreateTenantAction,Data/Central/,Http/Central/,routes/central.php). Code without the marker may assume a tenant is initialised; code with it must not touch tenant tables. - The tenant model extends stancl's and adds only what the mode needs. For a database per tenant:
implements TenantWithDatabaseanduse HasDatabase. AddHasDomainsonly when tenants are identified by domain or subdomain;$tenant->domains()doesn't exist without it. - Columns you query on
tenantsare listed ingetCustomColumns(). Any other attribute is stored in thedataJSON column, sowhere('name', …)against it finds nothing. - The tenant's key is public. It travels in the header, path or database name, so
models.id_generatorisULIDGeneratororUUIDGeneratorto match the project's public ids, never an incrementing int.tenantsis the one table whose primary key is stancl's string id rather than the auto-incrementidthat laravel-models keeps. - Every central model except
TenantusesCentralConnection(database per tenant). Once tenancy is initialised the default connection is the tenant's, so a central model without it queries the wrong database.Tenantgets it from stancl's base model. - Tenant models are plain models (database per tenant). No
tenant_idcolumn, no scoping trait, nowhere('tenant_id', …): the connection is the scope. - Relationships point from tenant to central, never back. A tenant model may
belongsToa central one, because the related query runs on the central model's connection. A central model can't reach tenant tables. Neither direction surviveswhereHas(),withCount()or a join, which run as one statement on one database. - Rules that check a central table name the model class.
Rule::exists(Plan::class, 'ulid')resolves the model's central connection;'exists:plans,ulid'looks in the tenant's database. - Creating a tenant provisions it.
Tenant::query()->create()firesTenantCreated, and the pipeline in the app'sTenancyServiceProvidercreates, migrates and seeds its database. Never do any of that by hand. Reference data every tenant needs (roles, defaults) goes in the tenant seeder named inseeder_parameters, written so it can run again; addSeedDatabaseto the pipeline, where the published stub leaves it commented out. - No
DB::transactionaround tenant creation. The database is created on a separate host connection, so rolling back the central transaction leaves an orphaned database behind. - Migrations are split. Central ones in
database/migrations/run withphp artisan migrate; tenant ones indatabase/migrations/tenant/(migration_parameters.--path) run withphp artisan tenants:migrate. Deploys run both. - Identification runs before anything that reads the database. The published
TenancyServiceProvidercallsmakeTenancyMiddlewareHighestPriority()so the identification middleware sorts ahead of authentication and route binding; keep it. - Identification isn't authorization. Anyone can send any tenant's header or visit any subdomain. With users in each tenant's database, authentication is already scoped: a user or token from one tenant doesn't exist in another. When users are central and belong to several tenants, every tenant route checks membership.
- Jobs need nothing tenancy-specific. Dispatched in a tenant's context, a job carries that tenant:
QueueTenancyBootstrapperstamps the tenant key into the payload and initialises tenancy on the worker before the job is unserialized. Never pass the tenant to the constructor or add a tenancy trait. Dispatched in central context, a job runs central. - Cache and files are scoped by config.
CacheTenancyBootstrapperprefixes keys on each store intenancy.cache.stores, andFilesystemTenancyBootstrappersuffixes the root of each disk intenancy.filesystem.disks. List every store and disk tenant code uses,s3included (the stub leaves it commented out). A value shared by every tenant goes throughGlobalCache. - The scheduler runs central. Scheduled work over tenant data fans out: the scheduler calls a central action that dispatches one job per tenant from inside that tenant's context, as in the example. A tenant query in a scheduled action without the fan-out reads the central database.
- Use stancl's API directly:
tenant()for the current tenant,$tenant->run(fn)to run code as a tenant,tenancy()->central(fn)to step out. Each restores the previous context. When the project wraps these in its own facade, use the wrapper.
Example
The scheduler's fan-out, central code that runs tenant work:
<?php
declare(strict_types=1);
namespace App\Actions\Central\Order;
use App\Jobs\ExpireStaleOrdersJob;
use App\Models\Tenant;
class ExpireStaleOrdersForAllTenantsAction
{
public function __invoke(): void
{
Tenant::query()
->lazyById()
->each(function (Tenant $tenant): void {
$tenant->run(function (): void {
ExpireStaleOrdersJob::dispatch();
});
});
}
}
The job is an ordinary job wrapping the tenant-side ExpireStaleOrdersAction (laravel-jobs); it runs in the tenant it was dispatched in, and one tenant's failure can't stop the others.
The tenant model, for a database per tenant:
<?php
declare(strict_types=1);
namespace App\Models;
use Database\Factories\TenantFactory;
use Illuminate\Database\Eloquent\Attributes\UseFactory;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Stancl\Tenancy\Database\Concerns\HasDatabase;
use Stancl\Tenancy\Database\Contracts\TenantWithDatabase;
use Stancl\Tenancy\Database\Models\Tenant as BaseTenant;
#[UseFactory(TenantFactory::class)]
class Tenant extends BaseTenant implements TenantWithDatabase
{
use HasDatabase, HasFactory;
public static function getCustomColumns(): array
{
return ['id', 'name'];
}
}
Identification
| When the project identifies tenants by | Middleware | Also |
|---|---|---|
| Domain or subdomain | InitializeTenancyByDomain, …BySubdomain or …ByDomainOrSubdomain | The tenant model uses HasDomains; the action that creates a tenant creates its domain with $tenant->domains()->create(['domain' => …]); identification.central_domains lists the app's own hosts |
| A path segment | InitializeTenancyByPath | Tenant routes are prefixed with {tenant} |
| A header (an API) | InitializeTenancyByRequestData | The header name is config (identification.resolvers.RequestDataTenantResolver.header, default X-Tenant), and the value is the tenant key; never subclass the middleware to change it |
Use the package middleware directly and set identification.default_middleware to it. A tenant surface's middleware group in the MiddlewareBooter lists it ($middleware->group('api_v1', [InitializeTenancyByRequestData::class])), stacked after api or web as laravel-routing describes. Central surfaces need nothing: a route without identification middleware is central, because default_route_mode is RouteMode::CENTRAL.
When tenants share one database
Leave DatabaseTenancyBootstrapper out of tenancy.bootstrappers and HasDatabase off the tenant model. Every tenant table has an indexed tenant_id, part of every unique index, and its model uses BelongsToTenant, which fills tenant_id on create and scopes queries to the current tenant. A model whose parent carries the tenant uses BelongsToPrimaryModel instead. The scope applies only while tenancy is initialised: central code sees every tenant's rows, so a central query over tenant tables filters deliberately. Unique and exists rules on tenant tables add ->where('tenant_id', tenant()->getTenantKey()).
Reach for these when the situation calls for it
A package keeps state that must differ per tenant (a cache key, a config value, a singleton's setting). Write a bootstrapper in app/Bootstrappers/, list it in tenancy.bootstrappers, and undo in revert() exactly what bootstrap() did:
use Spatie\Permission\PermissionRegistrar;
use Stancl\Tenancy\Contracts\TenancyBootstrapper;
use Stancl\Tenancy\Contracts\Tenant;
class PermissionCacheBootstrapper implements TenancyBootstrapper
{
private readonly string $baseKey;
public function __construct(private readonly PermissionRegistrar $registrar)
{
$this->baseKey = config('permission.cache.key');
}
public function bootstrap(Tenant $tenant): void
{
$this->registrar->cacheKey = "{$this->baseKey}.tenant.{$tenant->getTenantKey()}";
}
public function revert(): void
{
$this->registrar->cacheKey = $this->baseKey;
}
}
A job must always run central, wherever it's dispatched. Give it a queue connection with 'central' => true in config/queue.php; QueueTenancyBootstrapper leaves its payload untouched.
An artisan command does tenant work. Run an existing command per tenant with php artisan tenants:run {command}, or give a new one HasTenantOptions and TenantAwareCommand (both Stancl\Tenancy\Concerns) so it runs once per tenant and takes --tenants=.
Tenants share a host and the app uses sessions (path or header identification on the web). Add ScopeSessions after the identification middleware, so a session started in one tenant gets a 403 in another.
A route serves both contexts (a shared login or asset route). Add the universal middleware flag alongside the identification middleware.
Users exist centrally and in several tenants. stancl's resource syncing: the central model implements SyncMaster, the tenant model Syncable, both use ResourceSyncing, and the synced attributes are listed on each.
Testing
Tests that run in a tenant live in a Tenanted/ folder (tests/Feature/Tenanted/Api/V1/OrderTest.php) and run in one testing tenant, kept between runs, with both databases wrapped in a transaction per test. A test there reads like any other: it never creates or mentions the tenant, and HTTP calls carry the tenant automatically. Every other test runs central. The project keeps laravel-testing's one TestCase, but swaps FastRefreshDatabase for a tenancy-aware wrapper of it. Read references/tenancy-testing.md when setting up or changing that harness, or writing a central test that creates tenants. Test style is laravel-testing's.
Anti-patterns
- ❌ A tenant parameter or tenancy trait on a job.
- ❌
DB::transactionaroundTenant::query()->create(), or creating, migrating or seeding a tenant database by hand. - ❌
$tenant->domains()on a tenant model withoutHasDomains. - ❌ A central model without
CentralConnection, or a central model with a relationship to a tenant model. - ❌
tenant_idcolumns orwhere('tenant_id', …)in a database-per-tenant app. - ❌ A scheduled action that queries tenant tables without fanning out per tenant.
- ❌ A subclass of an identification middleware that only changes its header or domain.
- ❌
'exists:plans,ulid'for a central table in a tenant request. - ❌ Querying a tenant attribute that isn't in
getCustomColumns().
Related
- laravel-actions: actions, the sweep-and-dispatch pattern the fan-out follows
- laravel-jobs: the jobs the fan-out dispatches
- laravel-routing: surfaces, route files and their middleware groups
- laravel-providers: the MiddlewareBooter and ScheduleBooter
- laravel-models: model structure and public ids
- laravel-validation: Form Requests and their rules
- laravel-architecture: the layout the
Centralmarker sits in - laravel-testing: test style
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/leeovery/agentic-skills/laravel-multi-tenancy">View laravel-multi-tenancy on skillZs</a>