public const string API_MODE = 'sandbox'; — cette simple ligne ne compilait pas avant PHP 8.3. Le langage acceptait de déclarer une constante de classe, mais sans jamais vérifier ni imposer son type, ce qui laissait la porte ouverte à des erreurs silencieuses dans du code sensible comme une passerelle de paiement.
Sur une extension WC_Payment_Gateway maison, ces constantes servent souvent à figer des identifiants d’environnement, des formats de clé ou des codes de statut renvoyés par un prestataire. Les typer change concrètement la façon dont les erreurs de configuration remontent.
Le problème avec des constantes non typées
Avant PHP 8.3, une constante de classe pouvait recevoir n’importe quelle valeur sans que rien ne le signale au moment de l’écriture du code. Une constante censée contenir une chaîne de caractères pouvait très bien se retrouver affectée d’un entier ou d’un tableau à la suite d’une modification malheureuse, sans que l’interpréteur ne s’en plaigne avant l’exécution — et parfois seulement au moment précis où la passerelle tentait de construire une requête vers le prestataire de paiement.
Ce genre d’erreur est particulièrement pénible sur une passerelle : elle ne se déclenche pas à chaque commande, mais uniquement lorsque le chemin de code concerné est emprunté, par exemple lors d’un remboursement partiel ou d’une notification de webhook.
Ce que permet PHP 8.3
PHP 8.3 introduit la possibilité de déclarer un type sur une constante de classe, exactement comme on le fait déjà pour une propriété typée. Le moteur vérifie alors la compatibilité de la valeur assignée, et lève une erreur de compilation si le type ne correspond pas.
class Mon_Passerelle_Gateway extends WC_Payment_Gateway {
public const string ENVIRONNEMENT_SANDBOX = 'sandbox';
public const string ENVIRONNEMENT_PRODUCTION = 'production';
public const int TIMEOUT_SECONDES = 15;
public const array STATUTS_ACCEPTES = ['succeeded', 'paid', 'captured'];
protected function get_environnement(): string {
return $this->testmode ? self::ENVIRONNEMENT_SANDBOX : self::ENVIRONNEMENT_PRODUCTION;
}
}
Pourquoi c’est particulièrement utile sur une passerelle
Une passerelle de paiement manipule plusieurs catégories de constantes sensibles : les identifiants d’environnement, les codes de statut acceptés par le prestataire, les délais de tentative, parfois des chemins d’URL de rappel. Chacune de ces valeurs a une forme attendue précise, et une erreur de frappe dans une constante de type tableau (oublier une virgule, mettre une chaîne au lieu d’un tableau) peut casser silencieusement toute une logique de vérification de statut.
En typant ces constantes, l’erreur remonte au chargement de la classe plutôt qu’au moment où un client tente de payer, ce qui déplace le problème d’un environnement de production vers un environnement de développement ou d’intégration continue.
Variantes possibles
- Combiner une constante typée avec une énumération PHP (disponible depuis PHP 8.1) pour les statuts, plutôt qu’un simple tableau de chaînes.
- Utiliser une interface dédiée pour exposer les constantes publiques d’une passerelle, afin qu’une extension tierce puisse s’y référer sans dépendre de la classe concrète.
- Ajouter des propriétés
readonlytypées pour les valeurs calculées à la construction de l’objet, en complément des constantes fixes.
Un exemple avec une énumération
enum StatutPaiement: string {
case Reussi = 'succeeded';
case EnAttente = 'pending';
case Echoue = 'failed';
}Ce type d’énumération se combine bien avec des constantes typées : la constante référence le type de l’énumération plutôt qu’une simple chaîne, ce qui rend impossible l’assignation d’une valeur en dehors de la liste prévue.
Sur une extension de paiement, chaque valeur en dur mérite un type explicite : le coût de l’écriture est négligeable comparé au temps perdu à déboguer un statut mal comparé six mois plus tard.
Compatibilité et prérequis
Cette fonctionnalité nécessite que l’hébergement fasse tourner PHP 8.3 ou une version ultérieure. Avant de l’adopter sur une extension distribuée à des clients dont l’environnement n’est pas maîtrisé, il convient de vérifier la version minimale annoncée dans l’en-tête Requires PHP du plugin, et de prévoir un repli sans typage de constante pour les hébergements encore en PHP 8.1 ou 8.2.
En résumé
Le typage des constantes de classe n’est pas une fonctionnalité spectaculaire, mais c’est exactement le genre de garde-fou qui évite les erreurs les plus coûteuses à diagnostiquer : celles qui ne se manifestent que dans un cas précis, en production, sur une passerelle de paiement où chaque incident a un coût direct.
