Download the PHP package rupadana/filament-shield without Composer
On this page you can find all versions of the php package rupadana/filament-shield. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download rupadana/filament-shield
More information about rupadana/filament-shield
Files in rupadana/filament-shield
Package filament-shield
Short Description Filament support for `spatie/laravel-permission`.
License MIT
Homepage https://github.com/bezhansalleh/filament-shield
Informations about the package filament-shield
Shield
The easiest and most intuitive way to add access management to your Filament Admin:
- :fire: Resources
- :fire: Pages
- :fire: Widgets
- :fire: Custom Permissions
[!NOTE] For Filament 2.x use 2.x branch
[!IMPORTANT] Prior to
v3.1.0
Shield supported spatie/laravel-permission:^5.0
and now it supports version^6.0
. Which has some breaking changes around migrations. If you are upgrading from a version prior tov3.1.0
please make sure to remove the old migration file and republish the new one.
Installation
-
Install the package via composer:
-
Add the
Spatie\Permission\Traits\HasRoles
trait to your User model(s): -
Publish the
config
file then setup your configuration: -
Register the plugin for the Filament Panels you want
- Now run the following command to install shield:
Follow the prompts and enjoy!
Filament Panels
If you want to enable Shield
for more than one panel then you need to register the plugin for each panel as mentioned above.
Panel Access
Shield comes with the HasPanelShield
trait which provides an easy way to integrate Shield's conventions with the Filament's panel access system.
The HasPanelShield
trait provides an implementation for the canAccessPanel
method, determining access based on whether the user possesses the super_admin
role or the panel_user
role. It also assigns the panel_user
role to the user upon creation and removes it upon deletion. Ofcourse the role names can be changed from the plugin's configuration file.
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:
:bulb: 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.
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:
🅰️/🈯️ 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.
Configure Permission Identifier
By default the permission identifier is generated as follow:
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:
Warning Keep in mind that ensuring the uniqueness of the permission identifier is now up to you.
Custom Navigation Group
By default the english translation renders Roles and Permissions under 'Filament Shield' if you wish to change this, first publish the translations files and change the relative locale to the group of your choosing for example:
to
apply this to each language you have groups in.
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:
📕 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.
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:
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:
Policies
Role Policy
To ensure RoleResource
access via RolePolicy
you would need to add the following to your AuthServiceProvider
:
You can skip it if you have enabled it from the config
:
Policy Path
If your policies are not in the default Policies
directory in the app_path()
you can change the directory name in the config file:
Custom folder structure for Models or Third-Party Plugins
Shield also generates policies and permissions for third-party plugins and Models
with custom folder structure and to enforce the generated policies you will need to register them in your application's AuthServiceProvider
:
Users (Assigning Roles to Users)
Shield does not come with a way to assign roles to your users out of the box, however you can easily assign roles to your users using Filament Forms
's Select
or CheckboxList
component. Inside your users Resource
's form add one of these components and configure them as you need:
You can find out more about these components in the Filament Docs
Layout Customization
You can easily customize the Grid
, Section
and CheckboxList
's columns()
and columnSpan()
without publishing the resource.
Translations
Publish the translations using:
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--ignore-existing-policies
Do not overwrite the existing policies.
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
Testing
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
- Bezhan Salleh
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of filament-shield with dependencies
filament/filament Version ^3.0
spatie/laravel-package-tools Version ^1.9
spatie/laravel-permission Version ^5.0