Filament Shield: roles and permissions for Filament panels via spatie/laravel-permission

What Shield adds to a Filament panel that spatie/laravel-permission does not

spatie/laravel-permission gives you roles, permissions and the HasRoles trait. It has no idea that a Filament Resource named OrderResource needs view, create, update and delete permissions, or that a Widget needs a permission check before it renders. Shield is the layer that knows. It discovers the entities in your panels and turns them into permission keys, policies and a management UI. The audience is Laravel developers running one or more Filament panels who want per-entity access control without hand-writing a policy for every resource. The README describes the goal as "the easiest and most intuitive way to add access management to your Filament panels", and the feature list is organized around that: resource permissions, page permissions, widget permissions, custom permissions, automatic policy generation, a super admin role or gate interception, an optional baseline panel user role, multi-tenancy support and entity discovery across all panels when enabled. If your authorization needs stop at a handful of controllers outside Filament, Shield is more machinery than the problem requires.

How entity discovery turns Resources, Pages and Widgets into permission keys

The mechanism is generation, not runtime magic. Shield scans the Filament entities it can see, builds a permission key for each action, and writes policies for your resources. The keys are not fixed strings: the README documents configuration for permission key composition, a case setting, and customization of how keys are composed, so the naming convention is a config decision rather than a hardcoded one. Policies follow the same pattern. The README separates default policy methods for Filament Resources from per-resource policy definitions, and mentions third-party resource policy and permission generation, which is how a package that ships its own Filament resource gets covered. There is also a merge option, documented alongside single-parameter methods, for cases where you want generated methods combined with your own. Enforcement is the part worth reading closely: the README has distinct sections for policy enforcement and for page and widget permission enforcement, which means the check is not uniform across entity types. Super admin access can be granted through a role or through gate interception, and the README presents those as alternatives. A baseline panel user role is optional. That is a deliberate default: Shield does not assume every panel user should have a role on install.

Installing Filament Shield and running a first real use

The README lists three installation steps. First, require the package with Composer.

composer require bezhansalleh/filament-shield

Second, publish the config and set your auth provider model. The published file is config/filament-shield.php, and the key you edit is auth_provider_model.

php artisan vendor:publish --tag="filament-shield-config"

// config/filament-shield.php
return [
    // ...
    'auth_provider_model' => 'App\\Models\\User',
    // ...
];

Your auth provider model also needs the HasRoles trait from spatie/laravel-permission, otherwise there is nothing for Shield to attach roles to.

use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

Third, run the setup command. The README calls it interactive and smart, which is accurate in the sense that it asks questions rather than requiring a full config file up front.

php artisan shield:setup

After setup, the CLI is where the real work happens. The README documents core commands and a separate generate command with its own options, plus a seeder command for roles and direct permissions. The generate command is what produces permissions and policies; the seeder command is what turns them into seed data. The README also documents prohibited commands and what it calls safe prohibiting, which is the guard against running destructive generation commands in the wrong environment. Read that section before scripting Shield into a deploy pipeline. The bundled resource gives you a UI for roles and permissions, and the README notes it can be published and customized if the default layout does not fit.

The 4.x rewrite and the upgrade path that is not backward compatible

This is the limitation that matters most. The README states plainly that this iteration is a complete rewrite from versions 3.x and 4.x-beta and is not backward compatible, and it points readers to an Upgrade section for how to proceed. That means an existing 3.x installation cannot simply bump the constraint in composer.json. The compatibility table maps package versions to Filament versions: 2.x pairs with Filament 2.x, 3.x pairs with Filament 3.x, and 4.x pairs with Filament 4.x and 5.x. If your project is still on Filament 3, you are on the 3.x branch of Shield, not the current release line. The README also documents an upgrade path for the config file, so the published config from an older install is not expected to be valid as-is. Plan the upgrade as a migration with a branch, a regenerated permission catalogue and a re-run of the seeder, not as a patch release. The README does not document rollback, so if you need a reversible upgrade, that path is not described in the documentation.

Multi-tenancy support and where the configuration surface gets wide

Shield supports multi-tenancy, and the README has a dedicated tenancy section under the plugin and resource documentation, alongside navigation, labels, global search, parent resource and layout customization. The important detail is that entity discovery can run across all panels when enabled, which is convenient for a single-panel application and a decision point for a multi-tenant one: you need to know whether a permission key should be global or scoped per tenant, and the README's tenancy section is where that is addressed. The configuration surface is broad. Permissions, policies, resources, pages and widgets each have their own configuration section, plus localization with generated translation files and translation keys, plus custom permissions with formatting rules and externally managed permissions. None of that is hidden, but it does mean Shield is a package you configure rather than one you install and forget. The README's position is that the defaults are sensible and should work for most applications, which is a reasonable claim for a single-panel app and less obviously true once tenancy and multiple panels are in play.

Filament Shield compared with using spatie/laravel-permission directly

The honest alternative is spatie/laravel-permission on its own. The difference is where the integration work lives. With spatie alone, you define permission names yourself, write a policy for every Filament resource, and add permission checks to pages and widgets by hand. You get full control over naming and you carry the maintenance. Shield inverts that: it derives the permission catalogue from your Filament entities, generates the policies, and gives you a resource to assign roles and permissions in the panel. The cost is that your permission names are shaped by Shield's composition rules and its config, and the README documents a case setting and key composition customization precisely because teams have naming conventions that do not match the default. There is a middle position too: the README documents externally managed permissions and custom permissions, so you can keep some permissions under your own control while Shield handles the Filament-derived ones. If your permission model is unusual, or if most of your authorization happens outside Filament, spatie alone is the smaller dependency.

Maintenance, licensing and what to check before you commit

Shield is MIT licensed, so the licence implications are the permissive ones: you can use it in commercial and closed-source applications, and the LICENSE.md file in the repository is the authoritative text rather than any summary here. The repository is not archived, and the last push was on 2026-07-25, which is recent enough that the project is being worked on rather than parked. Release history supports that: 4.3.1 landed on 2026-07-25, 4.3.0 on 2026-07-23, and 4.2.0 on 2026-03-22. The upgrade cost is the real maintenance line item. Because 4.x is a rewrite, the cost of moving is concentrated at the upgrade rather than spread across releases, and the README's Upgrade section is the only documented path. For new projects the cost is the ongoing one: every time you add a Filament resource, page or widget, you regenerate permissions and re-run the seeder, and you keep the generated policies in sync with your entities. The repository layout includes a phpstan baseline, a pint config, a rector config and a test suite, which tells you the project is held to static analysis and formatting standards, but that is a statement about the repository, not a guarantee about your upgrade.

Editorial conclusion

Adopt Shield if your admin panel is Filament and you already accept spatie/laravel-permission as the authorization layer: the setup command, policy generation and the bundled resource remove most of the wiring. Do not adopt it if you need authorization outside a Filament panel, or if you are upgrading a 3.x install and cannot schedule the rewrite, because the README states this iteration is not backward compatible. Before committing, verify which Filament version your project pins against the compatibility table, confirm your auth provider model is set in config/filament-shield.php, and run the generate and seeder commands on a branch to inspect the permission keys and policies they produce.

Frequently asked questions

Official sources

1. bezhanSalleh/filament-shield on GitHub
2. Issues
3. License: MIT
4. README
5. Releases