Filament Shield

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

🔥 Resources
🔥 Pages
🔥 Widgets
🔥 Settings ^New

Support Filament

Upgrade

To upgrade to the latest release first run:

composer update

backup config.php(incase you have configured) then:

php artisan shield:upgrade

you can run this command without interaction by supplying the -no-interaction flag.

Installation

Install the package via composer:

composer require bezhansalleh/filament-shield

Publish the config file with:

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

Configure your options

<?php

return [

/*
    |--------------------------------------------------------------------------
    | Defualt Roles
    |--------------------------------------------------------------------------
    |
    | Permissions' generated will be assigned automatically to the following roles when enabled.
    | `filament_user` if enabled will help smoothly provide access to filament users
    | in production when implementing `FilamentUser` interface.
    */


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

    'filament_user' => [
        'role_name' => 'filament_user',
        'enabled' => false
    ],

    /*
    |--------------------------------------------------------------------------
    | Default Prefixes
    |--------------------------------------------------------------------------
    |
    | When generating permissions for a `Resource` the resource `Model` will be prefixed with these.
    | Keep in mind the order since these will also be used in generating policies for the resources.
    |
    | When generating permission for a `Widget` or `Page` the widget or page name will be prefixed
    | with this.
    | But you are free to change these in to whatever works for you.
    */

    'prefixes' => [
        'resource' => [
            'view',
            'view_any',
            'create',
            'delete',
            'delete_any',
            'update',
            'export', // custom resource permission
        ],
        'page'  =>  'view',
        'widget' => 'view'
    ],

    /*
    |--------------------------------------------------------------------------
    | Entities Permission Generator
    |--------------------------------------------------------------------------
    | Enable the Entities for which you want the permissions or permissions and policies
    | to be auto generated when you run `php artisan shield:install` command.
    */

    'entities' => [
        'pages' => true,
        'widgets' => true,
        'resources' => true,
        'custom_permissions' => false,
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Resources Generator Option
    |--------------------------------------------------------------------------
    | Here you may define the "generator" option for resources.
    | Sometimes it's beneficial to generate policies once locally, in case the production server
    | does not allow you to regenerate them (Laravel Vapor) or you have updated the policies.
    | Choose the option the fits best your use case.
    |
    | Supported options: "policies_and_permissions", "policies", "permissions"
    */

    'resources_generator_option' => 'policies_and_permissions',
    /*
    |--------------------------------------------------------------------------
    | Exclude
    |--------------------------------------------------------------------------
    | When enabled Exclude entites listed here during permission generation.
    |
    */

    'exclude' => [
        'enabled' => true,
        'pages' => [
            'Dashboard'
        ],
        'widgets' => [
            'AccountWidget',
            'FilamentInfoWidget'
        ],
        'resources' => [],
    ],

    /**
     * Register `RolePolicy` for `RoleResource`
     */
    'register_role_policy' => true,
];

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;

    // ...
}

Now run the following command to setup everything:

php artisan shield:install

Follow the prompts and enjoy!

Resource Custom Permissions

You can add custom permissions for the resources in addition to the required 6 by adding your custom permission names at the end of the resource key inside the prefixes config key array. For instance lets add export cutom permission to all resources:

...
'prefixes' => [
        'resource' => [
            'view',
            'view_any',
            'create',
            'delete',
            'delete_any',
            'update',
            'export', // custom resource permission
        ],
    ...
...

Since we have added our new custom permission, it's time to refresh the list of permissions for the resources by running:

php artisan shield:generate

Now, you can check and see in your Resources each resource listed will have an export permission as well.

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

📕 However if your page's mount() method requires a $record or other parameters it's best to handle that yourself instead of using HasPageShield.

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',
];
...

Translations

Publish the translations using:

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

Views

Publish the Views using:

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

Available Filament Shield Commands

- install   # One Command to Rule them All 🔥
- generate  # (Re)Discovers Filament resources and (re)generates Permissions and Policies.
- create    # Create Permissions and/or Policy for the given Filament Resource Model
- publish   # Publish filament shield's Resource.
- super-admin # Create a user with super_admin role
- upgrade # upgrade shield without hassle

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.

oyepez003 / filament-shield