permission_callback (REST)

Définition : La permission_callback est la fonction de contrôle d’accès associée à un endpoint WordPress REST. Elle décide si le demandeur peut effectuer l’opération avant l’exécution du traitement principal.

Comprendre et utiliser

À quoi sert cette notion ?

Elle protège les actions et données privées indépendamment de l’interface graphique. Le serveur vérifie la permission après les mécanismes d’authentification applicables.

Fonctionnement technique

La callback reçoit la requête et peut renvoyer true, false ou WP_Error. Un contrôle basé sur current_user_can() est préférable à une simple vérification de connexion lorsqu’une capacité métier existe.

Dans quel contexte l’utiliser ?

Un endpoint qui lit un dossier privé doit limiter son accès à un utilisateur possédant une capacité appropriée.

Étude de cas : application professionnelle

Considérer un endpoint capable de consulter un dossier technique associé à un utilisateur. Un contrôle fondé seulement sur « est connecté » serait insuffisant : deux utilisateurs connectés ne doivent pas nécessairement lire les mêmes dossiers. La permission_callback peut examiner l’identité, la capacité et l’identifiant demandé avant que le serveur ne lance le traitement. Réaliser un test avec deux comptes de rôles distincts puis un compte sans droits. Vérifier que les refus n’incluent pas les données sensibles dans leur message. Cette séparation entre identité et capacité constitue un principe majeur.

Exemple technique commenté

Cet extrait est destiné à un fichier PHP chargé par WordPress, idéalement dans un plugin local de test. Il ne doit pas être placé dans l'éditeur de contenu. Avant exécution, vérifier que les objets et variables mentionnés existent dans le contexte et que les permissions nécessaires sont définies.

<?php
$options = array(
    'permission_callback' => function ( WP_REST_Request $request ) {
        $id = absint( $request->get_param( 'id' ) );
        return $id > 0 && current_user_can( 'edit_post', $id );
    },
);
// Tableau partiel à intégrer dans register_rest_route().

Décryptage du code et résultat attendu

Le tableau contient uniquement la configuration d’une permission pour une route recevant id. Il n’enregistre aucun endpoint à lui seul. Le serveur devra disposer d’une callback principale et des autres options requises.

Exercice guidé pour vérifier la notion

À partir d’un plugin de test, essayer la même route avec un administrateur, un contributeur sans droit et un visiteur anonyme ; comparer les réponses.

Précautions et limites

Ne jamais retourner __return_true pour des données privées. Une nonce REST ne remplace pas l’autorisation sur l’objet, et l’identité connectée ne garantit pas le droit demandé.