bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

Fund package maintenance!
bezhanSalleh


README

filament-shield-art

FILAMENT 8.x Packagist Tests Passing Code Style Passing Downloads

Filament Shield

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

  • 🔥 Resources
  • 🔥 Pages
  • 🔥 Widgets
  • 🔥 Custom Permissions

Upgrade

To upgrade to the latest release first run:

composer update

v2.x

Note Minimum Filament Requirement is now 2.13.

Before following along, backup your current config first.

  1. 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 either follow Upgrade only
  2. Upgrade only

    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

Note for Filament prior to 2.13 use v1.1.12

Installation

  1. Install the package via composer:
composer require bezhansalleh/filament-shield
  1. 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

    // ...
}
  1. Publish the config using:
php artisan vendor:publish --tag=filament-shield-config
  1. Setup your configuration
<?php

    return [

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

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

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

          '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' => false
          ],
    ];
  1. Now run the following command to install shield:
php artisan shield:install

Follow the prompts and enjoy!

Resource Custom Permissions

You can add custom permissions for Resources through Config file.

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;
    ...
}

RolePolicy

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

  • One Command to Rule them All 🔥. This command publishes core package config, publishes core package migration, creates a filament user and discovers filament resources and generates Permissions and Policies accordingly.
  • Accepts a --fresh flag, that will refresh the core package tables and setup shield.

shield:generate

  • (Re)Discovers Filament resources and (re)generates Permissions and Policies.
  • The generator.option config value controls the scope of this command. Available options are policies_and_permissions, policies or permissions.
  • Accepts an --option= argument that will override the config file option setting.

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:upgrade

  • Upgrade shield.

Testing

composer test

Changelog

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

Contributing

If you want to contribute to this packages, you may want to test it in a real Filament project:

  • Fork this repository to your GitHub account.
  • Create a Filament app locally.
  • Clone your fork in your Filament app's root directory.
  • In the /filament-shield directory, create a branch for your fix, e.g. fix/error-message.

Install the packages in your app's composer.json:

"require": {
    "bezhansalleh/filament-shield": "dev-fix/error-message as main-dev",
},
"repositories": [
    {
        "type": "path",
        "url": "filament-shield"
    }
]

Now, run composer update.

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.