- How do I install Filament Shield in a Laravel app?
- Install bezhansalleh/filament-shield with Composer in an application that already has Filament and spatie/laravel-permission set up, then run Shield's installation command to publish its configuration and generate permissions and policies. Shield is a bridge between those two packages, so it does not bundle either of them. Confirm your Filament and spatie versions first, because Shield's constraint is tied to the Filament major you are on.
- Which Filament versions does Filament Shield support?
- The current release line targets Filament 4.x and 5.x, as shown by the README badges. Shield majors track Filament majors, so pin both packages together in composer.json rather than floating either constraint. Check the release notes for the exact supported combination before you upgrade Filament.
- Is Filament Shield v4 backward compatible with 3.x?
- No. The README states that this iteration is a complete rewrite from 3.x and 4.x-beta with no backward-compatible path, so upgrading is a migration project rather than a routine composer update. Read the Upgrade section carefully and budget for a permission-key diff and a policy review. Treat any Shield major bump as a scheduled migration, not a dependency bump.
- How does Filament Shield generate permissions and policies?
- Shield derives permission keys from your Filament resources, pages and widgets, then generates matching policy classes so you do not hand-write the eleven policy methods per resource. Generation is configurable through the buildPermissionKeyUsing callback, the policies.methods list, per-resource manage overrides and an exclude list, which keeps it a scaffold rather than a black box. Generated policies are written into app/Policies.
- Does Filament Shield support custom or ad-hoc permissions?
- Yes. Shield supports custom ad-hoc permissions in addition to the ones it derives from Filament components, which lets you protect actions that do not map cleanly to a resource, page or widget. You still assign those permissions through spatie/laravel-permission roles and the Shield admin UI. This is useful for one-off actions like exporting or approving records.
- How do I prevent permission key collisions in Filament Shield?
- The default subject is the model, so two resources with the same class name in different namespaces, such as a Blog Categories and a Shop Categories resource, generate identical permission keys unless you customize the composition. Use the buildPermissionKeyUsing callback to include namespace or module context in the key. Collisions cause silent over-granting, which ordinary unit tests will not catch.
- What happens if I change the permission key case or separator later?
- Case and separator are persisted decisions: Pascal case with a colon separator is the default, and those exact strings are stored in the permissions table. Changing them after launch means a data migration across permissions, role_has_permissions and model_has_permissions. Decide the format before you generate permissions for the first time.
- Will Filament Shield overwrite my hand-written policies?
- It depends on the policies.generate, policies.merge and policies.path settings. Setting merge to true is the safer choice, but regeneration still rewrites files, so custom authorization logic can be silently reverted if you regenerate without discipline. Review the generated diff before committing and keep bespoke logic where regeneration will not touch it.
- How do I make Shield work with models outside App\Models or plugin resources?
- Models outside App\Models, nested models and third-party plugin models are not resolved automatically. Register them explicitly with Gate::policy() or define a convention using Gate::guessPolicyNamesUsing so Laravel can locate the generated policy. This gap usually surfaces late, when a plugin resource is added to the panel.
- Is Filament Shield safe for production, and how should I test it?
- Shield is widely used and the repository ships a test workflow, but the real production risk is configuration drift rather than runtime failure. Write feature tests that assert a user without a permission receives a 403 and a user with it receives a 200, and cover the super-admin gate interception explicitly because blanket bypasses make incident reviews harder. Also verify behaviour after regeneration so policy changes are intentional.