Weave Code
Laravel Multitenancy Laravel Package
spatie/laravel-multitenancy
Unopinionated multitenancy for Laravel: detect the current tenant per request and define what happens when switching tenants. Supports single or multiple databases, tenant-aware queues/jobs, per-tenant artisan commands, and easy model connection switching.
Make your Laravel app usable by multiple tenants
Frequently asked questions about Laravel Multitenancy
- How do I set up tenant resolution for subdomains (e.g., tenant1.app.com) in Laravel Multitenancy?
- Use the `DomainTenantFinder` class to resolve tenants by subdomain. Bind it in your service provider with `TenantFinder::macro('domain', fn() => new DomainTenantFinder())`, then configure the subdomain pattern in the finder’s `resolve()` method. For example, `tenant1.app.com` maps to tenant ID `1`. Ensure your DNS routes subdomains to your Laravel app.
- Can I use a shared database schema instead of separate databases per tenant?
- Yes, the package supports shared schemas. Add a `tenant_id` column to your tables and configure Eloquent’s `connection()` method to dynamically switch contexts using `Tenant::actingAs()`. For queries, use `where('tenant_id', $tenantId)` or leverage Eloquent’s global scopes. Test thoroughly to avoid data leakage between tenants.
- How do I make queued jobs tenant-aware in Laravel Multitenancy?
- Implement the `TenantAware` interface in your job class or use the `TenantMiddleware` in your queue worker’s middleware stack. The package automatically resolves the tenant context for dispatched jobs. For custom logic, override the `resolveTenant()` method in your job. Always test background jobs with `Tenant::actingAs()` in your test cases.
- What Laravel versions does spatie/laravel-multitenancy support?
- The package officially supports Laravel 9.x and 10.x. Check the [Packagist page](https://packagist.org/packages/spatie/laravel-multitenancy) for the latest version compatibility. For older versions (e.g., Laravel 8), use the `^3.x` branch, but note that some features may lack support. Always test upgrades in a staging environment.
- How do I run Artisan commands for all tenants (e.g., migrations, cache clearing)?
- Use the `tenant:artisan` command provided by the package. Run `php artisan tenant:artisan migrate` to execute migrations for all tenants. For custom commands, extend the `TenantArtisan` class or loop through tenants manually. Combine with `--tenant=ID` to target specific tenants. Log output carefully to avoid mixing tenant-specific results.
- What’s the best way to test multitenancy in Laravel with this package?
- Mock tenant resolution in tests using `Tenant::actingAs($tenant)` or override the `TenantFinder` middleware. For shared schemas, test data isolation with `Tenant::withoutResolvingTenant()` to simulate landlord mode. Use `Tenant::actingAs()` in feature tests and `Tenant::actingAs()` + `DatabaseTransactions` for unit tests. Avoid global state leaks by resetting the tenant context after each test.
- How do I handle tenant-specific database connections (multi-database setup)?
- Configure your `.env` with tenant-specific database URLs (e.g., `DATABASE_CONNECTION_tenant1=mysql://...`). Use Eloquent’s `connection('tenant1')` in your models or leverage the package’s `TenantConnectionResolver`. For dynamic connections, bind a `TenantConnectionResolver` to the `db` service in your provider. Always validate connections during tenant switching.
- What happens if a tenant isn’t found during resolution? How do I handle landlord mode?
- By default, the package throws a `TenantNotFoundException`. To enable landlord mode (admin access), catch the exception and redirect to a login or dashboard. Alternatively, configure a fallback tenant in your `TenantFinder` (e.g., `return Tenant::findOrFail($id) ?? Tenant::landlord()`). Document this behavior in your error handling middleware.
- Are there performance considerations for high-traffic multitenancy apps?
- Tenant resolution adds minimal overhead (~1–5ms for DB queries). Cache resolved tenants in Redis using `Tenant::cacheResolvedTenant()` to reduce database load. For shared schemas, optimize queries with tenant-specific indexes. Monitor route caching (per-tenant caches increase file count) and use `tenant:artisan route:cache` sparingly. Load test with realistic tenant volumes.
- What alternatives exist to spatie/laravel-multitenancy for Laravel multitenancy?
- Alternatives include `stancl/tenancy` (opinionated, supports shared/multi-DB with migrations), `orchid/tenancy` (for Orchid platforms), or custom solutions using Laravel’s middleware and Eloquent scopes. `spatie/laravel-multitenancy` stands out for its unopinionated approach and deep Laravel integration. Evaluate based on your need for flexibility (spatie) vs. built-in features (stancl).
Weaver
How can I help you explore Laravel packages today?