Filament Shield Documentation

Run the interactive setup command to configure Shield in your application. This command is designed to be smart and guide you through the initial setup process.

php artisan shield:setup

To use Shield, you must configure your authentication provider model (e.g., User) to work with the package.

1. Publish the configuration file:

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

2. Set the auth_provider_model in config/filament-shield.php to your User model class.
3. Add the Spati\\Permission\\\|Traits\\\|HasRoles trait to your User model.

Upgrading to 4.x involves significant architectural changes. Follow these steps:

1. Backup your database.
2. Remove old files: Delete filament-shield.php config and any published RoleResource.
3. Update: Run composer require bezhansalleh/filament-shield.
4. Publish new assets:
   • php artisan vendor:publish --tag="filament-shield-config"
   • php artisan shield:publish --panel=admin
5. Handle Permissions:
   • Clean Slate: Run php artisan shield:setup --fresh.
   • Preserve Data: If you need to keep existing roles, you must manually add a FilamentShield::buildPermissionKeyUsing() closure to your AppServiceProvider to replicate the old permission key pattern (snake_case vs the new pattern).
6. Regenerate: Run shield:generate to ensure policies are up to date.

If your models are located in directories that Laravel's automatic policy discovery cannot find (such as nested under a custom policies.path or for vendor models), you must manually register them.

The easiest way is to use the FilamentShield::enforcePolicies() method in your application's boot() method within a Service Provider.

Features:

• Lazy Evaluation: You can pass a closure to gate enforcement per panel or tenant.
• Exclusions: Use the except parameter to skip specific models.
• Priority: Explicit Gate::policy() registrations always take precedence over Shield's enforcement.

Install the package using Composer to add it to your project.

composer require bezhansalleh/filament-shield

To automatically hide navigation items or restrict access to Pages and Widgets based on permissions, use the provided Shield traits within your class.

For Pages: Use the HasPageShield trait.

For Widgets: Use the HasWidgetShield trait.

// For Pages
namespace App\Filament\Pages;

use ...;
use BezhanSalleh\FilamentShield\Traits\HasPageShield;

class MyPage extends Page
{
    use HasPageShield;
    ...
}

// For Widgets
namespace App\Filament\Widgets;

use ...;
use BezhanSalleh\FilamentShield\Traits\HasWidgetShield;

class IncomeWidget extends LineChartWidget
{
    use HasWidgetShield;
}

To prevent accidental data loss in production environments, you can prohibit destructive Shield commands (like generate, install, setup, etc.) by calling the prohibit method in your service provider's boot() method.

You can prohibit commands individually or use the FilamentShield::prohibitDestructiveCommands() helper to prohibit all of them at once.

use BezhanSallehilament-shield//Facades\
use BezhanSalleh\FilamentShield\Commands;

public function boot(): void
{
    // Prohibit all destructive commands at once
    FilamentShield::prohibitDestructiveCommands($this->app->isProduction());
}

You can define ad-hoc permissions that do not belong to Resource, Page, or Widget categories by adding them to the custom_permissions array in your configuration file. These permissions will appear in a Custom Permissions tab within the Role Resource if the tab is enabled.

To enable the Custom Permissions tab in the Role Resource, set shield_resource.tabs.custom_permissions to true in your configuration.

'custom_permissions' => [
    'Impersonate:User' => 'Impersonate User',
    'Export:Order' => 'Export Orders',
],

Custom permission keys are formatted based on your case and separator settings. Shield's formatter is fault-tolerant and normalizes various input formats (snake_case, kebab-case, camelCase, etc.) before applying the target case.

If your permissions are managed by external providers (like Terraform or Keycloak) and must retain their exact key names, set format_custom_permission_keys to false in the permissions configuration block. This prevents any case conversion from being applied to custom permissions.

'permissions' => [
    'separator' => ':',
    'case' => 'pascal',
    'generate' => true,
    'format_custom_permission_keys' => false,
],

Shield provides permission models for Filament Pages and Widgets. By default, they require view permissions.

Pages Configuration

'pages' => [
    'subject' => 'class',
    'prefix' => 'view',
    'exclude' => [
        \Filament\Pages\Dashboard::class,
    ],
],

Widgets Configuration

'widgets' => [
    'subject' => 'class',
    'prefix' => 'view',
    'exclude' => [
        \Filament\Widgets\AccountWidget::class,
        \Filament\Widgets\FilamentInfoWidget::class,
    ],
],

Options

• subject: class (uses class name) or model (uses static getModel()).
• prefix: A string prepended to permission keys (e.g., Page:IconLibrary).
• exclude: List of entities to skip.

You can customize how permission keys are generated (naming conventions, separators, and casing) in the filament-shield.php configuration file.

Important Compatibility Rule: The separator must not conflict with the chosen case delimiter. For example, using _ with snake or - with kebab will throw an InvalidArgumentException because the system cannot distinguish the affix from the subject.

'permissions' => [
    'separator' => ':',
    'case' => 'pascal',
    'generate' => true,
    'format_custom_permission_keys' => true,
],