![filament-shield-art](https://user-images.githubusercontent.com/10007504/148662315-35d4bd74-fc1c-4f8c-8c02-689309b414b0.png)
Filament Shield
The easiest and most intuitive way to add access management to your Filament Admin:
- π₯ Resources
- π₯ Pages
- π₯ Widgets
- π₯ Custom Permissions
Table of contents
- 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
- Delete
Shield
folder fromApp\Filament\Resources
- Delete
filament-shield
fromresources\lang\vendor or lang\vendor
- Delete
filament-shield
fromresources\views\vendor
- Delete
filament-shield.php
fromConfig
- Now follow
Upgrade only
- Delete
-
Upgrade only
2.x
-
Publish the
Config
:php artisan vendor:publish --tag=filament-shield-config --force
-
Configure: Update the new
published config
based on yourbacked-up config
-
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 avaialble 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');
}
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'
],
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 configexclude
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.