README

A Laravel package to manage the relationship between users and Spatie roles, with a permission-driven UI, a configurable default role for new users, and webmaster provisioning. Built by El Flaco Programa (EFP).

Features

• User ↔ role management UI: list users, search by email (prefix match), filter by role, and update a user's roles.
• Permission-driven authorization: every action is authorized through policies that check permissions (never roles directly).
• Role hierarchy: `webmaster > chief > staff > [unknown roles] > registered

  (no role)`. Users only see and manage users ranked below them.

• Webmaster peers: optionally allow webmasters to manage other webmasters.
• Default role for new users: automatically assign a configurable role on registration (toggleable from the UI).
• Bilingual UI: English and Spanish, switchable from the settings page.
• Self-contained, responsive views styled with Tailwind CSS.

Requirements

Before installing the package, ensure your application meets the following prerequisites:

• PHP ^8.3
• Laravel ^13.0
• spatie/laravel-permission ^8.3 (installed and migrated)
• Laravel Breeze installed in the consuming application (provides the users table and authentication scaffolding).
• Your User model must use Spatie's HasRoles trait.

Installation

For detailed prerequisites, manual asset publishing, configuration options, and frontend customizations, please refer to our comprehensive Installation Guide.

Configuration

The published config file (config/efp-role-manager.php) lets you set:

• user_model — the application's user model (auto-resolved by default).
• routing — the URL prefix, route-name prefix, and middleware stack.
• layout — the Blade layout component used by the module views.
• roles / permissions — the role and permission names (renamable).
• webmaster.emails — the email(s) provisioned as webmaster on install.
• webmaster.can_manage_peers — allow webmasters to manage other webmasters.
• default_role — factory default for the new-user default role.
• localization — available locales and the default/fallback locale.
• pagination.per_page — users shown per page in the listing.

Settings precedence: runtime settings live in the database and take priority over the config file (DATABASE > CONFIG). The config values are the factory defaults; efp-role-manager:install seeds them into the database.

Usage

Once installed, visit the module (default: /efp-role-manager/users) as a user who holds one of the management permissions:

Rules enforced by the policies:

• No self-editing: nobody can change their own roles.
• Hierarchy: you can only manage users ranked below you.
• Webmaster peers: only webmasters can manage same-level peers, and only when webmaster.can_manage_peers is enabled.

Commands

Default role for new users

When enabled, users are assigned the configured default role upon registration (via Laravel's Registered event). The webmaster role can never be used as the default role. The feature and the role name are managed from the settings page.

Localization

The UI ships in English (default) and Spanish, switchable from the settings page. A middleware applies the selected locale on the module's routes only, so the rest of your application's locale is unaffected.

Upgrading & Uninstalling

• docs/upgrade.md
• docs/uninstallation.md

License

The MIT License (MIT). Built by El Flaco Programa (EFP).