# API des rôles

> Interface de programmation qui permet de créer, modifier ou supprimer des rôles utilisateurs WordPress et de leur attribuer des capacités précises.

- Auteur : Clément Hadrot
- Publié le : 2026-09-25
- Mis à jour le : 2026-09-25
- URL : https://wpmoderne.dev.wordpress-developpement.fr/lexique/api-des-roles/

Plutôt que de vérifier partout dans le code « cet utilisateur s'appelle-t-il administrateur ? », WordPress raisonne en capacités : un rôle n'est qu'un nom associé à un ensemble de capacités, et c'est cette API qui permet de manipuler cet ensemble.

## Fonctions clés

La fonction `add_role()` crée un nouveau rôle avec sa liste de capacités initiales, tandis que `remove_role()` le supprime. Pour ajuster un rôle existant sans le recréer, on récupère l'objet via `get_role()` puis on appelle ses méthodes `add_cap()` ou `remove_cap()` :

```
function ajouter_role_relecteur() {
  add_role( 'relecteur', 'Relecteur', array(
    'read'         => true,
    'edit_posts'   => true,
    'publish_posts' => false,
  ) );
}
register_activation_hook( __FILE__, 'ajouter_role_relecteur' );
```

Ce type d'appel se place typiquement dans un crochet d'activation d'extension, pour que le rôle soit créé une seule fois plutôt qu'à chaque chargement de page.

## À ne pas confondre

- Un rôle regroupe des capacités, mais on peut aussi attribuer une capacité directement à un utilisateur précis sans passer par un rôle, via `WP_User::add_cap()`.
- Modifier les capacités du rôle « administrator » lui-même est risqué : une erreur peut bloquer l'accès à l'administration pour tous les comptes.
- Les rôles créés par une extension doivent idéalement être supprimés lors de la désactivation, sous peine de laisser des rôles orphelins dans la base après désinstallation.
- Pour vérifier une permission dans le code, on préfère toujours tester la capacité concernée avec `current_user_can( 'edit_posts' )` plutôt que le nom du rôle, ce qui garde le code fonctionnel même si les rôles sont réorganisés par la suite.