- How does this package differ from Filament’s built-in tenancy?
- Filament’s built-in tenancy handles top-level tenants (e.g., companies). This package adds a *second-level* scope (e.g., regions, departments) that filters all Eloquent queries globally across the panel, including resources, widgets, and global search. It persists via URL parameters and integrates as a topnav dropdown.
- Which Laravel and Filament versions does this package support?
- The package requires PHP 8.2+, Filament v4.x or v5.x, and Livewire v3 or v4. If your project uses an older version, you may need to fork or wait for compatibility updates, as the package has hard dependencies on these versions.
- Do I need to modify every resource to support sub-tenant scoping?
- No. The package uses Laravel’s global query scopes to filter all Eloquent queries automatically, so you don’t need to update individual resources. Simply add the `HasSubtenantScope` trait to your models and configure the scopes in your Filament panel.
- How do I handle conflicts with existing global scopes (e.g., SoftDeletes)?
- Global scopes in this package apply *after* other scopes like SoftDeletes. However, if conflicts arise (e.g., unintended filtering), test thoroughly or adjust scope priority by reordering them in your model’s `$scopes` array or using middleware to conditionally apply scopes.
- Can I customize the topnav dropdown’s appearance or behavior?
- Basic customization is supported, such as icons, labels, and dynamic options via the `optionsQuery` callback. For deeper UI changes (e.g., branding, dynamic logic), you may need to extend the package’s Blade views or override its styles in your Vite theme.
- How does sub-tenant persistence work across sessions or devices?
- Sub-tenant selection persists via URL query parameters (e.g., `?subtenant=nyc`), so it works across sessions, devices, and even shared links. This also enables bookmarking and ensures consistency without requiring login.
- What performance considerations should I keep in mind?
- Global scopes apply to *all* queries, so ensure subtenant relationships (e.g., `subtenant_id`) are indexed on scoped models to avoid performance bottlenecks. Test with high query volumes, and consider lazy-loading or caching if needed.
- Can I use multiple sub-tenant types (e.g., regions *and* departments)?
- Yes, the package supports multiple scopes (e.g., `service_area`, `department`) defined in the `scopes()` array. Each scope can reference a different model, but all must share a similar structure (e.g., `company_id` for filtering by tenant).
- How do I prevent data leaks between sub-tenants (e.g., a user seeing another region’s data)?
- The package enforces scoping via Eloquent global queries, but you should also validate sub-tenant access in middleware or model policies. For example, ensure users can only select sub-tenants tied to their company via `optionsQuery`.
- What’s the upgrade path if Filament v6 breaks compatibility?
- Since the package relies on Filament’s internal APIs, a major Filament update may require a fork or waiting for an official update. Monitor the package’s GitHub for compatibility notes, and consider testing early with Filament’s beta releases.