Filament Shield

The easiest and most intuitive way to add access management to your Filament Admin:

🔥 Resources
🔥 Pages
🔥 Widgets
🔥 Custom Permissions

Filament Shield
Table of contents

Upgrade

To upgrade to the latest release first run:

composer update

v2.x

Note Minimum Filament Requirement is now 2.13. for older versions use v1.1.12

Before following along, backup your current config first.

Upgrade from 1.x
1. Delete Shield folder from App\Filament\Resources
2. Delete filament-shield from resources\lang\vendor or lang\vendor
3. Delete filament-shield from resources\views\vendor
4. Delete filament-shield.php from Config
5. Now follow Upgrade only
Upgrade only 2.x
1. Publish the Config:
```
php artisan vendor:publish --tag=filament-shield-config --force
```
2. Configure: Update the new published config based on your backed-up config
3. Install:
```
php artisan shield:upgrade
```

Installation

Install the package via composer:

composer require bezhansalleh/filament-shield

Add the Spatie\Permission\Traits\HasRoles trait to your User model(s):

use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles; //or HasFilamentShield

    // ...
}

Publish the config using:

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

Setup your configuration

<?php

    return [

          'shield_resource' => [
              'slug' => 'shield/roles',
              'navigation_sort' => -1,
              'navigation_badge' => true,
              'navigation_group' => true,
              'is_globally_searchable' => false,
              'show_model_path' => true,
          ],

          'auth_provider_model' => [
              'fqcn' => 'App\\Models\\User'
          ],

          'super_admin' => [
              'enabled' => true,
              'name'  => 'super_admin',
              'define_via_gate' => false,
              'intercept_gate' => 'before' // after
          ],

          'filament_user' => [
              'enabled' => true,
              'name' => 'filament_user'
          ],

          'permission_prefixes' => [
              'resource' => [
                  'view',
                  'view_any',
                  'create',
                  'update',
                  'restore',
                  'restore_any',
                  'replicate',
                  'reorder',
                  'delete',
                  'delete_any',
                  'force_delete',
                  'force_delete_any',
              ],

              'page' => 'page',
              'widget' => 'widget',
          ],

          'entities' => [
              'pages' => true,
              'widgets' => true,
              'resources' => true,
              'custom_permissions' => false,
          ],

          'generator' => [
              'option' => 'policies_and_permissions'
          ],

          'exclude' => [
              'enabled' => true,

              'pages' => [
                  'Dashboard',
              ],

              'widgets' => [
                  'AccountWidget','FilamentInfoWidget',
              ],

              'resources' => [],
          ],

          'register_role_policy' => [
              'enabled' => true
          ],
    ];

Now run the following command to install shield:

php artisan shield:install

Follow the prompts and enjoy!

Resources

Generally there are two scenarios that shield handles permissions for your Filament resources.

Default

Out of the box Shield handles the predefined permissions for Filament resources. So if that's all that you need you are all set. If you need to add a single permission (for instance lock) and have it available for all your resources just append it to the following config key:

    permission_prefixes' => [
        'resource' => [
            'view',
            'view_any',
            'create',
            'update',
            'restore',
            'restore_any',
            'replicate',
            'reorder',
            'delete',
            'delete_any',
            'force_delete',
            'force_delete_any',
            'lock'
        ],
        ...
    ],

💡 Now you are thinking what if I need a permission to be only available for just one resource? No worries, that's where Custom Permissions come to play.

Custom Permissions

To define custom permissions per Resource your Resource must implement the HasShieldPermissions contract. This contract has a getPermissionPrefixes() method which returns an array of permission prefixes for your Resource.

Consider you have a PostResource and you want a couple of the predefined permissions plus a new permission called publish_posts to be only available for PostResource only.

<?php

namespace BezhanSalleh\FilamentShield\Resources;

use BezhanSalleh\FilamentShield\Contracts\HasShieldPermissions;
...

class PostResource extends Resource implements HasShieldPermissions
{
    ...

    public static function getPermissionPrefixes(): array
    {
        return [
            'view',
            'view_any',
            'create',
            'update',
            'delete',
            'delete_any',
            'publish'
        ];
    }

    ...
}

In the above example the getPermissionPrefixes() method returns the permission prefixes Shield needs to generate the permissions.

✅ Now to enforce publish_post permission headover to your PostPolicy and add a publish() method:

    /**
     * Determine whether the user can publish posts.
     *
     * @param  \App\Models\User  $admin
     * @return \Illuminate\Auth\Access\Response|bool
     */
    public function publish(User $user)
    {
        return $user->can('publish_post');
    }

🅰️/🈯️ To make the prefix translatable, publish Shield's translations and append the prefix inside resource_permission_prefixes_labels as key and it's translation as value for the languages you need.

//lang/en/filament-shield.php
'resource_permission_prefixes_labels' => [
    'publish' => 'Publish'    
],
//lang/es/filament-shield.php
'resource_permission_prefixes_labels' => [
    'publish' => 'Publicar'    
],

Configure Permission Identifier

By default the permission identifier is generated as follow:

Str::of($resource)
    ->afterLast('Resources\\')
    ->before('Resource')
    ->replace('\\', '')
    ->snake()
    ->replace('_', '::');

So for instance if you have a resource like App\Filament\Resources\Shop\CategoryResource then the permission identifier would be shop::category and then it would be prefixed with your defined prefixes or what comes default with shield.

If you wish to change the default behaviour, then you can call the static configurePermissionIdentifierUsing() method inside a service provider's boot() method, to which you pass a Closure to modify the logic. The Closure receives the fully qualified class name of the resource as $resource which gives you the ability to access any property or method defined within the resource.

For example, if you wish to use the model name as the permission identifier, you can do it like so:

use BezhanSalleh\FilamentShield\Facades\FilamentShield;

FilamentShield::configurePermissionIdentifierUsing(
    fn($resource) => str($resource::getModel())
        ->afterLast('\\')
        ->lower()
        ->toString()
);

Warning Keep in mind that ensuring the uniqueness of the permission identifier is now up to you.

Pages

If you have generated permissions for Pages you can toggle the page's navigation from sidebar and restricted access to the page. You can set this up manually but this package comes with a HasPageShield trait to speed up this process. All you have to do is use the trait in you pages:

<?php

namespace App\Filament\Pages;

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

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

📕 HasPageShield uses the booted method to check the user's permissions and makes sure to execute the booted page method in the parent page if exists.

Pages Hooks

However if you need to perform some methods before and after the booted method you can declare the next hooks methods in your filament page.

<?php

namespace App\Filament\Pages;

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

class MyPage extends Page
{
    use HasPageShield;
    ...

    protected function beforeBooted : void() {
        ...
    }

    protected function afterBooted : void() {
        ...
    }

    /**
     * Hook to perform an action before redirect if the user
     * doesn't have access to the page.  
     * */
    protected function beforeShieldRedirects : void() {
        ...
    }
}

Pages Redirect Path

HasPageShield uses the config('filament.path') value by default to perform the shield redirection. If you need to overwrite the rediretion path, just add the next method to your page:

<?php

namespace App\Filament\Pages;

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

class MyPage extends Page
{
    use HasPageShield;
    ...

    protected function getShieldRedirectPath(): string {
        return '/'; // redirect to the root index...
    }
}

Widgets

if you have generated permissions for Widgets you can toggle their state based on whether a user have permission or not. You can set this up manually but this package comes with a HasWidgetShield trait to speed up this process. All you have to do is use the trait in you widgets:

<?php

namespace App\Filament\Widgets;

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

class IncomeWidget extends LineChartWidget
{
    use HasWidgetShield;
    ...
}

Role Policy

You can skip this if have set the 'register_role_policy' => true in the config. To ensure RoleResource access via RolePolicy you would need to add the following to your AuthServiceProvider:

//AuthServiceProvider.php
...
protected $policies = [
    'Spatie\Permission\Models\Role' => 'App\Policies\RolePolicy',
];
...

Third-Party Plugins

Shield also generates policies and permissions for third-party plugins and to enforce the generated policies you will need to register them in your application's AuthServiceProvider:

...
class AuthServiceProvider extends ServiceProvider
{
    ...
    protected $policies = [
        ...,
        'Ramnzys\FilamentEmailLog\Models\Email' => 'App\Policies\EmailPolicy'

    ];

Same applies for models inside folders.

Translations

Publish the translations using:

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

Available Filament Shield Commands

`shield:doctor`

Show useful info about Filament Shield.

`shield:install`

Setup Core Package requirements and Install Shield. Accepts the following flags:

--fresh re-run the migrations
--only Only setups shield without generating permissions and creating super-admin

`shield:generate`

Generate Permissions and/or Policies for Filament entities. Accepts the following flags:

--all Generate permissions/policies for all entities
--option[=OPTION] Override the config generator option(policies_and_permissions,policies,permissions)
--resource[=RESOURCE] One or many resources separated by comma (,)
--page[=PAGE] One or many pages separated by comma (,)
--widget[=WIDGET] One or many widgets separated by comma (,)
--exclude Exclude the given entities during generation
--ignore-config-exclude Ignore config exclude option during generation

`shield:super-admin`

Create a user with super_admin role.

Accepts an --user= argument that will use the provided ID to find the user to be made super admin.

`shield:publish`

Publish the Shield RoleResource and customize it however you like

`shield:seeder`

Deploy easily by setting up your roles and permissions or add your custom seeds

`shield:upgrade`

Upgrade shield.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

bezhanSalleh/filament-shield

bezhanSalleh

Reviews

Repository Details