Weave Code
Laravel Multitenancy Laravel Package
spatie/laravel-multitenancy
An unopinionated Laravel package that makes your app tenant aware. It determines the current tenant per request, handles switching tenants, and supports single or multi-database setups, plus tenant-aware queued jobs and artisan commands.
spatie/laravel-multitenancy makes a Laravel app tenant aware while staying deliberately unopinionated—it provides only the bare essentials for multitenancy. It determines the current tenant for each request and lets you define what happens when switching tenants, supporting both single- and multi-database setups. The package adds practical niceties for real-world projects without locking you into one strategy.
- Tenant-aware queued jobs and artisan commands that run per tenant
- Simple ways to set a database connection on models
- Configurable tenant switching behavior
- Support for multiple multitenancy strategies
Frequently asked questions about Laravel Multitenancy
- How do I install spatie/laravel-multitenancy in a Laravel app?
- Install the package with Composer, publish its config, implement the IsTenant contract on your tenant model, and choose a tenant finder such as DomainTenantFinder or a custom finder. Then register any switch tasks needed for your application. The package baseline is PHP 8.2+ and Laravel 11+.
- Does spatie/laravel-multitenancy support multiple databases per tenant?
- Yes. It supports both single-database tenancy and database-per-tenant setups. Multi-database mode adds connection, migration, and configuration complexity, while single-database mode requires careful query scoping and protection against raw SQL leakage.
- Which Laravel and PHP versions does spatie/laravel-multitenancy require?
- The evaluated baseline is PHP 8.2+ and Laravel 11+. You should still verify the exact Composer constraints for the package version you adopt. Version 4 also introduced breaking contract changes, so upgrade testing matters.
- How does spatie/laravel-multitenancy identify the current tenant?
- It resolves the current tenant per request using a tenant finder, with DomainTenantFinder provided and custom finders supported. The resolved IsTenant implementation is bound into the container via currentTenant. If no tenant is resolved, the current tenant is simply null, so your app needs an explicit policy for that case.
- Can queued jobs and artisan commands be tenant-aware?
- Yes. The package supports tenant-aware queued jobs and can run artisan commands for each tenant, using the switch-task pipeline to handle tenant changes. Long-running workers still need a deliberate state-reset strategy.
- Is spatie/laravel-multitenancy safe with Octane, Horizon, and queue workers?
- It can be used with long-lived processes, but it does not make tenant state automatically safe there. Octane, Horizon, and queue workers retain container state, facades may resolve once, a non-tenant-aware job can inherit a previous tenant, and app('currentTenant') can remain set if not explicitly forgotten. You need explicit reset logic and leak-detection tests.
- What is the difference between spatie/laravel-multitenancy and stancl/tenancy?
- spatie/laravel-multitenancy is an unopinionated enabling layer: it provides tenant resolution, switching, queue awareness, per-tenant artisan execution, and a per-model connection helper. It does not provide tenant provisioning, admin UI, billing, lifecycle management, or a full tenancy platform. stancl/tenancy and tenancy/tenancy are better comparisons when you want a more turnkey framework.
- How should I handle requests where no tenant is resolved?
- The package does not decide for you; when no tenant is resolved, the current tenant is null. You should define an explicit policy such as returning a 404, falling back to a landlord context, or failing hard. Apply that policy consistently at every entry point.
- What breaking changes are in spatie/laravel-multitenancy v4?
- Version 4 introduced breaking contract changes, including removal of UsesTenantModel and IsTenant signature changes on finders and tasks. Treat upgrades with disciplined testing rather than assuming minor-version compatibility. Review your tenant model, finder, and switch-task implementations before upgrading.
- Does spatie/laravel-multitenancy provide tenant provisioning, billing, or an admin UI?
- No. It deliberately provides only the bare essentials to make a Laravel app tenant aware, such as tenant resolution, switching, queue awareness, per-tenant artisan commands, and a per-model connection helper. Provisioning, suspension, deletion, export, billing, admin UI, and lifecycle management remain your responsibility. If you want more built-in lifecycle tooling, consider a more opinionated tenancy framework.
Weaver
How can I help you explore Laravel packages today?