SystemRoles Docs

Getting Started

Introduction

On this page

SystemRoles is a role and permission management package for Laravel. It gives your application:

  • Roles such as Super Admin, Admin, Manager and User.
  • Permissions for each role (for example course.update or invoice.approve), stored as a matrix you switch on and off per role.
  • One role per user, with a full history of every role change.
  • Controller access: mark which roles may use which controllers.
  • Route access: store every route of your app and mark which roles may use it.
  • A ready-made admin area at /systemroles/admin to manage all of the above, protected so only the super admin can open it.
  • Helpers to check roles and permissions from your own code.

SystemRoles is built by Solomon Bareebe and released under the MIT licence.

Who it is for#

SystemRoles suits applications where:

  • an administrator, not a developer, should decide what each role can do, through a screen rather than code;
  • each user has exactly one role;
  • you want the role setup stored in plain database tables you can read, report on and back up.

If you need many roles per user, team-scoped roles or per-model permissions, a package such as Spatie Laravel Permission may fit better. SystemRoles focuses on a simple role model that non-developers can manage.

How the pieces fit together#

users ──< user_roles >── system_roles ──< system_roles_in      (permission matrix)
                │                    ├──< system_classes_in    (controller access)
                │                    └──< system_routes_in     (route access)
                └── user_roles_history                         (every change logged)
  1. You create roles (system_roles).
  2. You create permissions. Each permission exists once per role in system_roles_in, switched on (1) or off (0).
  3. You give each user one role (user_roles). Every change is written to user_roles_history.
  4. Your code asks SystemRoles questions such as "is this user the super admin?" or "does role 3 have course.update?".

The package stores and manages the rules. Your application decides where to check them (in middleware, controllers, policies or Blade). The package's own admin area is the only part it protects by itself. See Protecting Routes with Middleware.

Features at a glance#

Feature Where
Create, edit and order roles Admin → Roles
Permission matrix per role, ordering Admin → Roles → Manage
All permissions across all roles Admin → Permissions
Assign a role to a user (DataTables user list) Admin → Users
Controller access per role (auto-scanned) Admin → Classes
Route list sync php artisan systemroles:sync
Super admin middleware super_admin
Static helpers SystemRolesService / SystemRoles facade
Role change history user_roles_history table

Next steps#