- How does stancl/tenancy handle tenant identification without requiring custom code?
- The package uses middleware-based tenant resolution by default, primarily via hostname or subdomains (e.g., `tenant.example.com`). You can also define custom resolvers in the `tenancy.php` config for scenarios like API keys, JWT claims, or route parameters. No model traits or global overrides are needed—just configure the resolver in the middleware pipeline.
- Will stancl/tenancy work with my existing Laravel application with minimal changes?
- Yes, the package is designed for zero-code changes. It automatically isolates database connections, cache, storage, and queues per tenant without requiring model traits or replacing Laravel core classes like `Cache` or `Storage`. However, audit your app for global scopes or middleware that assume a single database connection, as these may need adjustments.
- Does stancl/tenancy support shared tables (e.g., users, roles) across tenants, or is it strictly database-per-tenant?
- The package enforces strict database-per-tenant isolation by default, meaning all data is tenant-scoped. Shared tables are not supported out of the box, but you can configure custom database connections or use middleware to handle hybrid setups. For shared data, consider a separate central database or a hybrid approach with careful tenant context management.
- How do I set up tenant databases automatically during migrations or `migrate:fresh`?
- Use the `migrate-fresh --tenant` Artisan command to create and migrate tenant databases automatically. The package provides helpers like `Tenant::createDatabase()` and `Tenant::dropDatabase()` for programmatic control. For bulk operations, you can loop through tenants and execute migrations per database, though performance may vary with large tenant counts.
- Are queue jobs tenant-aware in stancl/tenancy, or do I need to manually handle tenant context?
- Queue jobs are not tenant-aware by default. You must use the `QueueTenancyBootstrapper` to inject the tenant context before job execution. Alternatively, store tenant IDs in job payloads and resolve the tenant context manually in the job’s `handle()` method. Serialization issues may arise if passing model instances, so use IDs or tenant-aware serializers.
- Can I use stancl/tenancy with Laravel Vite for tenant-specific assets (e.g., CSS/JS)?
- Yes, the package includes built-in Vite support for tenant-scoped assets. Use the `tenant-assets:publish` Artisan command to publish tenant-specific assets, and configure Vite to generate tenant-aware asset paths. For dynamic tenant resolution, use the `TenantMiddleware` to set the tenant context before asset compilation.
- What’s the performance impact of tenant resolution middleware under high traffic?
- Tenant resolution adds minimal latency (~1–5ms per request) due to middleware execution, but this can scale with tenant count or slow database connections. Benchmark your setup under load, especially if using subdomains or custom resolvers. Connection pooling (e.g., PDO or database-level) can mitigate overhead, but tenant database isolation remains the primary bottleneck for high-traffic apps.
- How do I handle errors when a tenant isn’t found or resolution fails?
- By default, unrecognized tenants trigger a `TenantNotFoundException`, which you can catch in middleware or a global exception handler. Configure a fallback (e.g., redirect to a central app, show a 404, or log the event) in the `tenancy.php` config under `fallback`. For API responses, return a `404` or custom JSON error with tenant resolution details.
- Does stancl/tenancy support PostgreSQL or SQLite, and how are schemas managed?
- Yes, the package supports PostgreSQL, SQLite, MySQL, and MariaDB. Schema management is handled automatically via Laravel migrations, but tenant databases must be created separately (e.g., using `Tenant::createDatabase()`). For SQLite, each tenant gets a separate file, while PostgreSQL/MySQL use dedicated databases. Schema changes require running migrations per tenant.
- What are the alternatives to stancl/tenancy for Laravel multi-tenancy, and when should I choose them?
- Alternatives include `spatie/laravel-multitenancy` (for shared databases with tenant columns) and `orchid/tenancy` (for SaaS platforms with user-based isolation). Choose stancl/tenancy if you need strict database-per-tenant isolation with minimal code changes and deep Laravel integration. Use `spatie/laravel-multitenancy` for shared schemas or `orchid/tenancy` for user-centric SaaS apps with complex permissions.