Roles & Permissions
Manage user access control programmatically with Spatie Laravel Permission.
Shopper uses spatie/laravel-permission to manage roles and permissions. Every admin user has one or more roles, and each role has a set of permissions that control access to admin panel sections and actions. Since all permissions are registered on Laravel's gate, you can use Laravel's built-in can() function and @can Blade directive.
For a visual walkthrough of managing roles and permissions in the admin panel, see the User Guide pages: Managing Staff and Roles & Permissions.
Configuration
Roles are configured in config/shopper/admin.php. These names are used throughout the system for authorization checks:
'roles' => [
'admin' => 'administrator',
'manager' => 'manager',
'user' => 'user',
],| Role | Purpose | Admin Access |
|---|---|---|
administrator | Full access to all admin panel features | Yes |
manager | Access limited to the permissions you give the role (none by default) | Yes |
user | Customer role. Shopper gives it to customers created in the admin panel; give it to customers who register on your storefront too, because the customers list only shows users with this role | No |
A user with any other role can open the admin panel only if they hold the access_dashboard permission (see System Permissions).
Do not rename roles after they have been assigned to users. Role names are used in middleware and authorization checks throughout the system.
Models
Role
The model used is Shopper\Models\Role, which extends Spatie's Role model with additional fields.
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
name | string | no | - | Unique role name used in authorization checks (e.g., administrator) |
guard_name | string | no | auto | Filled automatically by Spatie |
display_name | string | yes | null | Human-readable name |
description | text | yes | null | Role description |
can_be_removed | boolean | no | true | Whether the role can be deleted |
The Role model provides an isAdmin() method, which returns true when the role name matches shopper.admin.roles.admin:
use Shopper\Models\Role;
$role = Role::query()->where('name', config('shopper.admin.roles.admin'))->first();
$role->isAdmin(); // truePermission
The model used is Shopper\Models\Permission, which extends Spatie's Permission model with grouping support.
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
name | string | no | - | Permission name (e.g., browse_products) |
guard_name | string | no | auto | Filled automatically by Spatie |
group_name | string | yes | null | Permission group for organization |
display_name | string | yes | null | Human-readable name |
description | string | yes | null | Permission description |
can_be_removed | boolean | no | true | Whether the permission can be deleted |
Permission Groups
Each permission belongs to a group through its group_name column, and the role page in the admin panel lists permissions by group. Permission::groups() returns the built-in groups, used as the options of the group select when you create or generate a permission in the admin panel:
use Shopper\Models\Permission;
Permission::groups();This returns an array keyed by group name, with a translated label for each: system, brands, categories, collections, products, customers, orders, discounts.
System Permissions
The system group contains the global capabilities that gate everything outside the resource permissions:
| Permission | Description |
|---|---|
access_dashboard | Opens the admin panel for a user who has neither the administrator nor the manager role (checked by canAccessDashboard()) |
access_setting | Required to open the settings pages (General, Payment methods, Currencies, Carriers, Zones, Taxes, Legal) and for every write action on the Team, Roles and Permissions pages |
view_users | Required to view the team pages: the staff list, and a role page with its permissions and members |
Locations are not covered by access_setting: their pages check the inventory permissions (browse_inventories, add_inventories, edit_inventories, delete_inventories). The customers pages check the customer permissions (browse_customers, read_customers, and so on).
Since v2.8, access_setting is the only permission that grants write access to PaymentMethods, Currencies, Carriers, Team management, and Role/Permission management. Roles that previously relied on view_users to mutate these surfaces must be granted access_setting to keep working.
Team Management Safeguards
Holding access_setting grants write access to the team settings surfaces, but since v2.11.2 it no longer grants unrestricted control over the access control system itself, so you can give it to a staff member who configures shipping or taxes without handing them control of roles and permissions. Non administrator users are subject to three rules:
| Rule | Effect |
|---|---|
| The administrator role cannot be targeted | A non administrator cannot open, update, delete the administrator role, or assign it to a new team member |
| A permission can only be granted if the acting user holds it | A staff member cannot give a role a capability they do not have themselves |
| Permission definitions are administrator only | Creating, generating or deleting a permission requires the administrator role |
Administrators are unaffected: each rule is skipped when the acting user has the administrator role. Removing a team member is also limited to administrators, and an administrator account cannot be removed from the panel. Permissions and roles flagged with can_be_removed set to false are also protected on the server, not only hidden in the UI.
Generating Permissions
The Permission::generate() method creates five permissions for a given resource (browse, read, edit, add, delete):
Permission::generate('brands');
// Creates: browse_brands, read_brands, add_brands, edit_brands, delete_brands
Permission::generate('tags', 'products');
// Creates: browse_tags, read_tags, add_tags, edit_tags, delete_tags (in the "products" group)Without a second argument, the group is the resource name. Generated permissions have can_be_removed set to false, and the method gives them to no role: assign them yourself (see Creating Custom Permissions). The Generate permissions action on a role page in the admin panel calls the same method and gives the five permissions to that role.
Working with Roles
Creating Roles
To create a new role programmatically:
use Shopper\Models\Role;
$role = Role::query()->create([
'name' => 'warehouse-manager',
'display_name' => 'Warehouse Manager',
'description' => 'Manages inventory locations and stock levels.',
]);
$role->givePermissionTo([
'access_dashboard',
'browse_inventories',
'read_inventories',
'edit_inventories',
'browse_products',
'read_products',
]);The access_dashboard permission lets users with this role open the admin panel. Without it, only the administrator and manager roles get in.
Assigning Roles
Assign a role to a user:
$user->assignRole('warehouse-manager');
$user->assignRole(config('shopper.admin.roles.admin'));Checking Roles
The InteractsWithShopper trait on the User model provides role checking methods:
$user->isAdmin(); // true if user has the administrator role
$user->isManager(); // true if user has the manager role
$user->canAccessDashboard(); // true for administrators, managers and users holding access_dashboard
$user->hasRole('warehouse-manager');The trait also adds two query scopes:
use App\Models\User;
User::query()->administrators()->get(); // users with the administrator or manager role
User::query()->customers()->get(); // users with the user roleWorking with Permissions
Checking Permissions
Use Laravel's standard authorization:
$user->hasPermissionTo('browse_products');
$user->can('edit_products');In Blade templates:
@can('browse_products')
<a href="{{ route('shopper.products.index') }}">Products</a>
@endcanIn Livewire components, Shopper uses the authorize() method:
public function mount(): void
{
$this->authorize('browse_products');
}Creating Custom Permissions
To add a custom permission and assign it to the administrator and manager roles:
use Shopper\Models\Permission;
use Shopper\Models\Role;
$permission = Permission::query()->create([
'name' => 'view_analytics',
'group_name' => 'system',
'display_name' => 'View Analytics',
'description' => 'Access the analytics dashboard.',
]);
$roles = Role::query()
->whereIn('name', [
config('shopper.admin.roles.admin'),
config('shopper.admin.roles.manager'),
])
->get();
foreach ($roles as $role) {
$role->givePermissionTo($permission);
}Administrators get no automatic pass on permission checks. The installer gave the administrator role every permission that existed at that time, nothing more, so give each permission you create later to the administrator role too, or can() returns false for administrators.
On the role page in the admin panel, a permission without a group_name is listed under a "Custom permission" heading. A permission whose group_name is not one of the built-in groups is listed under a heading named after its group_name.
Revoking Permissions
To remove a permission from a role:
$role->revokePermissionTo('delete_products');Admin User Creation
You can create an admin user from the command line:
php artisan shopper:userThe command asks for the email, first name, last name and password (at least 6 characters), then gives the new user the administrator role.
Or programmatically. forceCreate() saves the attributes even when they are not in your User model's $fillable, as the command does:
use App\Models\User;
use Illuminate\Support\Facades\Hash;
$admin = User::query()->forceCreate([
'first_name' => 'John',
'last_name' => 'Doe',
'email' => 'admin@example.com',
'password' => Hash::make('password'),
'email_verified_at' => now(),
]);
$admin->assignRole(config('shopper.admin.roles.admin'));Components
To customize the roles and permissions admin UI:
php artisan shopper:component:publish settingThe relevant components in config/shopper/components/setting.php:
use Shopper\Livewire;
return [
'pages' => [
'team-index' => Livewire\Pages\Settings\Team\Index::class,
'team-roles' => Livewire\Pages\Settings\Team\RolePermission::class,
],
'components' => [
'settings.team.permissions' => Livewire\Components\Settings\Team\Permissions::class,
'settings.team.users' => Livewire\Components\Settings\Team\UsersRole::class,
'slide-overs.create-team-member' => Livewire\SlideOvers\CreateTeamMember::class,
],
];Last updated on
Edit on GitHub