nilsframework/nils-roles

Module de gestion des rôles et permissions pour NilsFramework — single et multi-rôles configurable

dev-main 2026-04-19 18:20 UTC

Requires

• php: >=8.1
• nilsframework/nils: ^1.0
• nilsframework/nils-auth: ^1.0
• nilsframework/nils-database: ^1.0
• nilsframework/nils-orm: ^1.0

MIT

• Traore

README

Module de gestion des rôles et permissions pour NilsFramework.
Supporte le mode single rôle (défaut) et multi-rôles configurable via config.json.

📋 Table des matières

• Installation
• Configuration
• Migration SQL
• Intégration dans le routeur
• Utilisation sur les routes
• RoleService
• Routes disponibles
• Wildcard permissions

Installation

composer require nilsframework/nils-roles

Configuration

Dans Configuration/config.json :

{
    "auth": {
        "multi_roles": false
    }
}

Valeur	Comportement
false (défaut)	Un user = un seul rôle → colonne role_id dans nils_users
true	Un user = plusieurs rôles → table pivot nils_user_roles

Migration SQL

mysql -u root -p ma_base < vendor/nilsframework/nils-roles/migrations/roles_tables.sql

Mode single (défaut) — décommentez dans le SQL :

ALTER TABLE nils_users ADD COLUMN role_id BIGINT UNSIGNED NULL AFTER actif;
ALTER TABLE nils_users ADD FOREIGN KEY (role_id) REFERENCES nils_roles(id) ON DELETE SET NULL;

Tables créées :

Table	Description
nils_roles	Rôles (admin, membre...)
nils_permissions	Permissions (users.voir, groupes.creer...)
nils_role_permissions	Pivot rôle ↔ permission
nils_user_roles	Pivot user ↔ rôles (mode multi uniquement)

Intégration dans le routeur

Dans core/Routeur.php, dans diriger(), après le bloc #[Auth] :

foreach ($refMethodAuth->getAttributes() as $attr) {
    $instance = $attr->newInstance();

    // Auth
    if ($instance instanceof \NilsAuth\Auth) {
        $headers       = new \core\Headers($requete->headers);
        $requete->auth = \NilsAuth\AuthMiddleware::verifier($headers, $instance->guard);
    }

    // HasRole
    if ($instance instanceof \NilsRoles\HasRole && $requete->auth) {
        \NilsRoles\RoleMiddleware::verifierRole($requete->auth, $instance->role);
    }

    // HasPermission
    if ($instance instanceof \NilsRoles\HasPermission && $requete->auth) {
        \NilsRoles\RoleMiddleware::verifierPermission($requete->auth, $instance->permission);
    }
}

Utilisation sur les routes

use NilsAuth\Auth;
use NilsRoles\HasRole;
use NilsRoles\HasPermission;

// Connecté uniquement
#[Get('/profile'), Auth]
public function profile(array $auth): void { }

// Rôle requis
#[Get('/admin'), Auth, HasRole('admin')]
public function admin(array $auth): void { }

// Permission requise
#[Get('/users'), Auth, HasPermission('users.voir')]
public function users(array $auth): void { }

// Rôle + permission
#[Delete('/users/{id}'), Auth, HasRole('admin'), HasPermission('users.supprimer')]
public function destroy(Params $params, array $auth): void { }

// Wildcard
#[Get('/users'), Auth, HasPermission('users.*')]
public function index(array $auth): void { }

RoleService

use NilsRoles\RoleService;

// Rôles d'un user
$roles = RoleService::rolesUtilisateur($userId);
// ['admin', 'moderateur']

// Vérifier un rôle
$ok = RoleService::aRole($userId, 'admin'); // bool

// Permissions d'un user
$perms = RoleService::permissionsUtilisateur($userId);
// ['users.voir', 'users.creer', 'groupes.voir']

// Vérifier une permission
$ok = RoleService::aPermission($userId, 'users.voir'); // bool

// Assigner un rôle
RoleService::assignerRole($userId, $roleId);

// Retirer un rôle (mode multi uniquement)
RoleService::retirerRole($userId, $roleId);

Routes disponibles

Rôles

Méthode	Route	Description
GET	/roles	Liste des rôles
POST	/roles	Créer un rôle
GET	/roles/{id}	Détail + permissions
PATCH	/roles/{id}	Modifier un rôle
DELETE	/roles/{id}	Supprimer un rôle
POST	/roles/{id}/permissions/{perm_id}	Assigner une permission
DELETE	/roles/{id}/permissions/{perm_id}	Retirer une permission

Permissions

Méthode	Route	Description
GET	/permissions	Liste des permissions
POST	/permissions	Créer une permission
GET	/permissions/{id}	Détail
PATCH	/permissions/{id}	Modifier
DELETE	/permissions/{id}	Supprimer

Utilisateurs

Méthode	Route	Description
GET	/users/{id}/roles	Rôles d'un user
GET	/users/{id}/permissions	Permissions d'un user
POST	/users/{id}/roles/{role_id}	Assigner un rôle
DELETE	/users/{id}/roles/{role_id}	Retirer un rôle (multi)

Wildcard permissions

// users.* → couvre users.voir, users.creer, users.modifier, users.supprimer
HasPermission('users.*')

// *.voir → couvre users.voir, groupes.voir, roles.voir
HasPermission('*.voir')

// Match exact
HasPermission('users.voir')

Licence

MIT — © NilsFramework