README

A comprehensive roles and permissions module for Sauce Base built on top of Spatie Laravel Permission.

Installation

Install via Composer:

composer require saucebase/roles
composer dump-autoload
php artisan module:enable Roles
php artisan module:migrate Roles
php artisan module:seed Roles
npm run build

Features

This module extends Spatie Laravel Permission with Sauce Base-specific enhancements:

Predefined Role System — Admin and User roles with enum-based type safety
Automatic Role Assignment — New users are automatically assigned the User role via UserObserver
Enhanced User Model — Extended HasRoles trait with convenience methods:
- isAdmin() and isUser() helper methods
- getRole() and getRoleLabel() attribute accessors
- Type-safe role checking with Role enum
Database Seeding — Automatic role creation via module:seed Roles command
Filament Integration — Modular plugin system ready for admin panel integration
Module Structure — Organized codebase following Sauce Base module conventions

For complete role and permission management features (middleware, blade directives, caching, etc.), see the Spatie Laravel Permission documentation.

Configuration

User Model Setup

Add the HasRoles trait to your User model:

use Modules\Roles\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;

    // ... rest of your model
}

Middleware Registration

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(append: [
        HandleInertiaRequests::class,
        AddLinkHeadersForPreloadedAssets::class,
        // ...
    ]);

    // Register Spatie Permission Middleware
    $middleware->alias([
        'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
        'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
        'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
    ]);

Usage

Available Roles

The module comes with predefined roles:

Admin — Full access to Filament panel and dashboard
User — Limited access to dashboard features

Assigning Roles

use Modules\Roles\Enums\Role;

// Assign role to user
$user->assignRole(Role::ADMIN);
$user->assignRole(Role::USER);

// Check if user has role
if ($user->hasRole(Role::ADMIN)) {
    // User is admin
}

// Get user roles
$roles = $user->roles;

Route Protection

Protect routes using middleware:

// Require specific role
Route::middleware(['role:admin'])->group(function () {
    Route::get('/admin', AdminController::class);
});

// Require any of multiple roles
Route::middleware(['role:admin|user'])->group(function () {
    Route::get('/dashboard', DashboardController::class);
});

Filament Admin Panel Protection

The Filament admin panel is protected with the role:admin middleware. This is configured in app/Providers/Filament/AdminPanelProvider.php:

->authMiddleware([
    Authenticate::class,
    'role:admin',
])

Creating Admin Users:

# Via Artisan Tinker
php artisan tinker

# Create an admin user
$user = App\Models\User::create([
    'name' => 'Admin User',
    'email' => 'admin@example.com',
    'password' => bcrypt('password'),
]);

$user->assignRole('admin');

Or via Seeder/Factory:

$admin = User::factory()->create();
$admin->assignRole(Role::ADMIN);

Only users with the admin role can access /admin panel. Regular users will get a 403 Forbidden response.

For more advanced usage, refer to the Spatie Laravel Permission documentation.

Testing

The module includes unit tests to verify the automatic role assignment functionality:

# Run all Roles module tests
vendor/bin/phpunit modules/Roles/tests/

# Run specific UserObserver tests
vendor/bin/phpunit modules/Roles/tests/Unit/UserObserverTest.php

Tests verify:

New users are automatically assigned the User role
Role assignment doesn't create duplicates
Observer doesn't interfere with manually assigned roles

saucebase / roles

Maintainers

Details