Skip to content

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',
],
RolePurposeAdmin Access
administratorFull access to all admin panel featuresYes
managerAccess limited to the permissions you give the role (none by default)Yes
userCustomer 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 roleNo

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.

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Unique role name used in authorization checks (e.g., administrator)
guard_namestringnoautoFilled automatically by Spatie
display_namestringyesnullHuman-readable name
descriptiontextyesnullRole description
can_be_removedbooleannotrueWhether 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(); // true

Permission

The model used is Shopper\Models\Permission, which extends Spatie's Permission model with grouping support.

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Permission name (e.g., browse_products)
guard_namestringnoautoFilled automatically by Spatie
group_namestringyesnullPermission group for organization
display_namestringyesnullHuman-readable name
descriptionstringyesnullPermission description
can_be_removedbooleannotrueWhether 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:

PermissionDescription
access_dashboardOpens the admin panel for a user who has neither the administrator nor the manager role (checked by canAccessDashboard())
access_settingRequired 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_usersRequired 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:

RuleEffect
The administrator role cannot be targetedA 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 itA staff member cannot give a role a capability they do not have themselves
Permission definitions are administrator onlyCreating, 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 role

Working 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>
@endcan

In 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:user

The 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 setting

The 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