SystemRoles Docs

Getting Started

Installation

On this page

Requirements#

Requirement Version
PHP 8.0 or newer
Laravel 9 or newer (tested on Laravel 12)
Database MySQL / MariaDB (other databases supported by Laravel migrations should work)
Authentication Any Laravel auth setup that logs users in and defines a route named logout (Breeze, Jetstream, Fortify, laravel/ui)
Users table users with an unsigned big integer id (the Laravel default)

The user_roles and user_roles_in tables have foreign keys to users.id. If your users.id is a plain INT, the migrations will fail. Change the column to BIGINT UNSIGNED first, or edit the published migrations.

1. Install with Composer#

Bash
composer require baberuka/systemroles

To track the latest development version straight from GitHub, add the repository to composer.json and require dev-main:

JSON
"repositories": [
    { "type": "vcs", "url": "https://github.com/BabeRuka/systemroles.git" }
],
"require": {
    "baberuka/systemroles": "dev-main"
}

2. Register the service provider#

Laravel's package auto-discovery registers the provider and the SystemRoles facade for you. Nothing else is needed.

If you have turned auto-discovery off (for example with "dont-discover" in composer.json), register them yourself.

Laravel 11 and 12, in bootstrap/providers.php:

PHP
return [
    App\Providers\AppServiceProvider::class,
    BabeRuka\SystemRoles\Providers\SystemRolesServiceProvider::class,
];

Laravel 9 and 10, in config/app.php:

PHP
'providers' => [
    // ...
    BabeRuka\SystemRoles\Providers\SystemRolesServiceProvider::class,
],

'aliases' => [
    // ...
    'SystemRoles' => BabeRuka\SystemRoles\Facades\SystemRoles::class,
],

The provider class is BabeRuka\SystemRoles\Providers\SystemRolesServiceProvider (note the Providers namespace).

3. Publish the files#

Bash
# Required: CSS, JS, fonts, images used by the admin screens
php artisan vendor:publish --tag=systemroles-assets

# Recommended: the config file, so you can change settings
php artisan vendor:publish --tag=systemroles-config

# Optional: the Blade views, if you want to restyle the admin screens
php artisan vendor:publish --tag=systemroles-views

# Optional: copy the seeder into database/seeders
php artisan vendor:publish --tag=systemroles-seeders
Tag Copies To
systemroles-assets assets/css, js, fonts, images, favicon, addons public/vendor/systemroles/
systemroles-config config/systemroles.php config/systemroles.php
systemroles-views resources/views/systemroles resources/views/vendor/systemroles/
systemroles-seeders database/seeders/SystemRolesSeeder.php database/seeders/

The admin screens load Bootstrap, DataTables and icon fonts from public/vendor/systemroles. If you skip the assets step, the screens open without styling.

4. Run the migrations#

Bash
php artisan systemroles:migrate

This runs only the SystemRoles migrations. The provider also registers them with Laravel, so a normal php artisan migrate picks them up too. Every migration checks whether its table already exists, so running both is safe.

Tables created:

Table Holds
system_roles Roles
system_roles_in Permission matrix (one row per permission per role)
user_roles The role of each user
user_roles_history Every role change
user_roles_in Snapshot of a user's permissions, refreshed when their role changes
system_classes, system_classes_in Controllers and which roles may use them
system_routes, system_routes_in Routes and which roles may use them
system_menus, system_menus_in, system_menu_items Menus (experimental)

See Database Schema and Models for every column.

5. Seed the default roles#

Bash
php artisan db:seed --class="Database\Seeders\SystemRolesSeeder"

This creates four roles with fixed ids:

role_id Name Guard name
1 Super Admin super_admin
2 Admin admin
3 Manager manager
4 User user

The seeder uses insertOrIgnore, so it never overwrites roles you already have. If you skip this step, the same four roles are created the first time the Roles screen opens on an empty table.

6. Make yourself the super admin#

The admin area only opens for the super admin, and no user has a role yet. Give your own account the super admin role once, from Tinker:

Bash
php artisan tinker
PHP
BabeRuka\SystemRoles\Models\UserRoles::create([
    'user_id'   => 1,   // your users.id
    'user_role' => 1,   // the super admin role id
    'role_type' => 'system',
]);

After this, every other role change can be done from the admin screens.

7. Check it works#

Log in as that user and open:

https://your-app.test/systemroles/admin/roles/index

You should see the roles list. If you are sent back to /dashboard with "Access Denied", see Troubleshooting.

Next steps#