current_user_can( 'gerer_factures' ) : cette vérification, écrite par un développeur un mardi après-midi, entrera très probablement en collision avec une capacité du même nom déclarée par une tout autre extension installée sur le même site, quelques mois plus tard, par un collègue qui n’a jamais lu le code du premier. Ce n’est pas une hypothèse rare : les noms de capacités génériques se répètent naturellement d’un développeur à l’autre, précisément parce qu’ils décrivent une action métier courante.
Pour une équipe qui structure les permissions d’une extension complexe, développée à plusieurs mains sur la durée, une convention de nommage explicite et un registre partagé évitent ce genre de collision silencieuse. Ce billet ne traite pas les rôles natifs de WordPress, mais la création de capacités personnalisées propres à une extension.
Pourquoi une capacité générique finit par entrer en collision
WordPress stocke les capacités personnalisées comme de simples chaînes de caractères associées à un rôle, sans aucune notion d’espace de noms. Rien n’empêche techniquement deux extensions différentes de déclarer, chacune de son côté, une capacité nommée gerer_factures ou valider_commande. Si les deux extensions attribuent cette capacité à des rôles différents pour des raisons différentes, un utilisateur peut se retrouver avec un accès non désiré à une fonctionnalité de l’une simplement parce qu’il possède déjà la capacité de même nom accordée par l’autre.
Adopter un préfixe systématique, y compris pour les capacités
Le réflexe de préfixer les noms de fonctions et les métadonnées est déjà largement répandu pour éviter les collisions. Il s’applique tout aussi bien aux capacités personnalisées, avec un format court mais explicite, dérivé du préfixe déjà utilisé ailleurs dans l’extension.
// À éviter : trop générique, risque de collision élevé
'gerer_factures'
// À privilégier : préfixé selon la convention de l'extension
'mxfact_gerer_factures'Le préfixe n’a pas besoin d’être long : trois à cinq caractères dérivés du nom de l’extension suffisent généralement, à condition qu’il reste identique partout où l’extension déclare une capacité, sans variation d’un développeur à l’autre.
Tenir un registre partagé, pas seulement une convention orale
Une convention de nommage non documentée finit toujours par être appliquée de façon inégale au sein d’une équipe. Un fichier de registre, versionné avec le code, liste chaque capacité déclarée, sa signification et le rôle auquel elle est attribuée par défaut. Ce fichier devient la référence consultée avant de créer une nouvelle capacité, plutôt que de se fier à la mémoire de l’équipe.
// registre-capacites.php — à consulter avant toute nouvelle déclaration
return [
'mxfact_gerer_factures' => 'Créer et modifier les factures (rôle : comptable)',
'mxfact_valider_paiement' => 'Valider un paiement enregistré (rôle : comptable, administrateur)',
'mxfact_exporter_donnees' => 'Exporter les données comptables (rôle : administrateur uniquement)',
];Attribuer les capacités à l’activation, pas à chaque chargement
Les capacités personnalisées doivent être attribuées aux rôles concernés lors de l’activation de l’extension, via register_activation_hook(), et retirées à la désinstallation, jamais recalculées à chaque chargement de page. Cette approche évite un appel répété à add_cap() sur chaque requête, coûteux et inutile puisque l’attribution, une fois faite, persiste dans la base de données.
register_activation_hook( __FILE__, function () {
$role_comptable = get_role( 'mxfact_comptable' );
if ( $role_comptable ) {
$role_comptable->add_cap( 'mxfact_gerer_factures' );
$role_comptable->add_cap( 'mxfact_valider_paiement' );
}
} );Garder map_meta_cap lisible malgré le préfixe
Le préfixage ne doit pas rendre les vérifications de permission illisibles dans le reste du code. Une constante ou une fonction utilitaire, définie une seule fois, permet de garder des appels concis sans répéter le préfixe complet à chaque vérification.
function mxfact_cap( string $suffixe ) : string {
return 'mxfact_' . $suffixe;
}
if ( current_user_can( mxfact_cap( 'gerer_factures' ) ) ) {
// Traitement autorisé
}En résumé
Deux extensions suffisent pour qu’un nom de capacité générique entre en collision, sans qu’aucune erreur visible ne signale le problème avant qu’un utilisateur ne se retrouve avec un accès inattendu. Un préfixe systématique, appliqué dès la première capacité déclarée, et un registre partagé consulté avant toute nouvelle déclaration, suffisent à éviter ce risque pour une équipe qui fait évoluer une extension complexe sur la durée.
