- How do I install leek/filament-subtenant-scope in a Laravel app?
- Install it with composer require leek/filament-subtenant-scope, which requires PHP 8.2+, Filament v4 or v5, and Livewire v3 or v4. Next, add a @source directive pointing at vendor/leek/filament-subtenant-scope/resources/views/**/*.blade.php in the panel theme configured with viteTheme(), then run npm run build so the dropdown's responsive utility classes are compiled. Finally, register SubtenantScopingPlugin on your panel and declare one or more SubtenantScope entries.
- Is this package compatible with Filament v5 and Livewire v4?
- Yes. The package supports Filament v4.x and v5.x alongside Livewire v3 and v4, and requires PHP 8.2 or newer. Because it hooks into Filament panel configuration, topnav, resources, widgets, and global search, you should pin compatible versions and re-test whenever you upgrade Filament or Livewire majors.
- How is this different from Filament's built-in multi-tenancy?
- Filament's built-in tenancy scopes the panel to a single tenant, such as a Company. This plugin adds a second, softer level on top of that, letting users further narrow everything to a service area, region, branch, location, or department. The result is a hierarchy like Company to Region to Branch without writing per-resource filtering logic.
- How do I register a sub-tenant scope on a Filament panel?
- Call SubtenantScopingPlugin::make()->scopes([...]) inside your panel's panel() method, passing one or more SubtenantScope instances. Each scope takes a key, a label, the model class, and the foreign key column, for example SubtenantScope::make('service_area', 'Service Area', ServiceArea::class, 'service_area_id')->icon('heroicon-o-map-pin')->labelAttribute('name'). You can also constrain the selectable options with optionsQuery(), typically to restrict records to the current user's company.
- Does the selected sub-tenant persist across navigation and logins?
- Yes. The active sub-tenant selection persists across navigation and survives logout and login, so users return to the same filtered view. It is also stored in the URL as a query parameter, which makes filtered views shareable, bookmarkable, and reproducible across sessions.
- Do I need to change every Eloquent model to make the scoping work?
- No. You add the package's subtenant scope trait to the models that carry the sub-tenant foreign key, and the package applies a Laravel global query scope across the panel. Confirm the exact trait name, referenced as HasSubtenantScopes, against the package documentation for your installed version. Every resource, widget, navigation badge, and global search result then filters automatically without per-resource code.
- Why does the sub-tenant dropdown label collapse or look unstyled?
- The plugin's blade views use Tailwind utility classes such as hidden sm:inline that must be compiled into your panel CSS. Add the @source directive for vendor/leek/filament-subtenant-scope/resources/views/**/*.blade.php to your viteTheme stylesheet and rebuild assets with npm run build. Without that step the label can collapse on wide screens or the dropdown can render incorrectly.
- What was fixed in version 1.0.4 of filament-subtenant-scope?
- Version 1.0.4 is a patch release with no apparent breaking changes. It fixes ambiguous column errors when scoped queries join tables that share the same subtenant foreign key, which matters for dashboards, reporting screens, and custom resource queries. It also teleports the topnav dropdown so it is no longer clipped in overflow-constrained layouts.
- Will global query scoping hurt performance on large tables?
- Global scopes apply broadly, so index the subtenant_id columns you scope on and the foreign keys used in common join paths. The patch release introduces no known performance regression, but reporting-style queries that aggregate across relationships should have their query plans validated. Watch for scope interactions with soft deletes, custom scopes, and other plugin global scopes.
- How should I test and roll out a sub-tenant scope safely in production?
- Write regression tests that prove cross-subtenant data isolation in resources, widgets, global search, exports, and custom actions, since a leak here is a real data exposure risk. Pay particular attention to joined queries where duplicate foreign-key column names caused ambiguity before v1.0.4. For rollout, run composer update, clear caches, rebuild frontend assets, and re-check the topbar dropdown in nested panels, mobile breakpoints, and your custom theme before deploying.