First-class callable syntax pour déclarer un permission_callback plus lisible

'permission_callback' => array( $this, 'verifier_acces' ),

Cette ligne, présente dans des centaines de contrôleurs REST WordPress, a un défaut discret : elle ne ressemble à rien pour un outil d’analyse statique. Un tableau à deux éléments, dont le second est une chaîne de caractères, ne dit à personne — ni à l’IDE, ni au développeur qui relit trois mois plus tard — qu’il s’agit en réalité d’un appel de méthode. PHP 8.1 corrige ce défaut avec la syntaxe des callables de première classe.

Cette nouvelle écriture, disponible depuis la sortie de PHP 8.1 fin novembre 2021, permet de transformer n’importe quelle méthode ou fonction en une véritable closure d’un trait de parenthèses suivies de points de suspension. Elle change peu de choses à l’exécution, mais beaucoup à la lecture et à la navigation dans le code.

L’ancienne écriture et ses limites

Le tableau [$this, 'methode'] est un callable valide depuis toujours en PHP, et WordPress l’utilise massivement dans register_rest_route(), aussi bien pour l’argument callback que pour permission_callback. Le problème n’est pas fonctionnel : PHP sait parfaitement résoudre ce tableau en un appel de méthode au moment de l’exécution. Le problème est outillage. La chaîne 'methode' est une simple chaîne de caractères aux yeux de la plupart des IDE ; un renommage de méthode par recherche-remplacement automatique la manque fréquemment, et le clic droit « aller à la définition » ne fonctionne pas toujours de façon fiable sur ce genre de construction.

La nouvelle syntaxe

Avec PHP 8.1, la même intention s’écrit :

register_rest_route( 'cabinet/v1', '/dossiers', array(
    'methods'             => 'GET',
    'callback'            => $this->lister_dossiers(...),
    'permission_callback' => $this->verifier_acces(...),
) );

La différence tient aux trois points après le nom de la méthode, appelés first-class callable syntax. PHP transforme $this->verifier_acces(...) en une véritable closure liée à l’instance courante, strictement équivalente à Closure::fromCallable( array( $this, 'verifier_acces' ) ) mais sans les inconvénients d’écriture de cette dernière forme. Le nom de la méthode devient un vrai symbole du langage : l’IDE le résout, le suit, et le signale en rouge s’il est renommé ou supprimé sans que l’appel soit mis à jour.

Un contrôleur avant / après

Sur un contrôleur REST personnalisé de taille moyenne, gérant quatre routes avec leurs permissions respectives, la migration reste mécanique :

• Repérer chaque occurrence de array( $this, 'nom' ) dans les arguments de route
• La remplacer par $this->nom(...), en conservant exactement le même nom de méthode
• Vérifier qu’aucune méthode visée n’est appelée avec des arguments statiques (la syntaxe first-class ne fige aucun argument, contrairement à Closure::bind avec des paramètres pré-remplis)

Sur un contrôleur réel de ce projet, comportant sept déclarations de ce type, l’opération a pris moins de dix minutes et n’a changé aucun comportement observable côté front : les mêmes routes REST répondent exactement de la même façon, avec les mêmes vérifications de permission.

Ce que ça ne change pas

Cette syntaxe reste purement une question d’écriture et de lisibilité. Elle ne modifie ni la vitesse d’exécution de façon perceptible, ni le comportement de register_rest_route(), ni la façon dont WordPress résout le callable au moment de traiter la requête. Elle ne fonctionne également que sur un contexte où $this est disponible, ou sur un nom de fonction global appelé sans variable : impossible par exemple d’utiliser cette syntaxe pour référencer dynamiquement une méthode dont le nom est stocké dans une variable, cas qu’on rencontre parfois dans des contrôleurs très génériques bâtis autour d’une table de routage.

Une compatibilité à vérifier avant d’adopter

Avant de généraliser cette écriture sur un projet, il reste indispensable de vérifier la version minimale de PHP exigée par l’hébergement de production. PHP 8.1 n’est pas systématiquement disponible sur tous les environnements début 2022, et un code utilisant cette syntaxe provoquera une erreur de syntaxe fatale sur un serveur resté en PHP 8.0 ou antérieur. Un simple contrôle dans le fichier composer.json, avec une contrainte "php": ">=8.1", permet d’éviter la mauvaise surprise lors du déploiement.

En résumé

La syntaxe des callables de première classe ne révolutionne pas la déclaration des routes REST, mais elle en améliore sensiblement la lisibilité et la maintenabilité à long terme. Sur un contrôleur qui accumule permissions et callbacks, remplacer chaque tableau à deux éléments par un appel de méthode suivi de trois points redonne à l’IDE une compréhension réelle du code, sans toucher au comportement observé côté API. Un gain modeste à l’exécution, mais réel au quotidien pour quiconque relit ou fait évoluer ces contrôleurs.