« Fatal error: Uncaught Error: Class « WC_Data_Exception » not found » — ce message apparaît généralement dans les journaux d’erreurs quelques minutes après le déploiement d’une extension fraîchement packagée avec Composer, souvent lors de son tout premier appel à une fonctionnalité liée aux données WooCommerce. Le code fonctionnait pourtant parfaitement en environnement de développement local.
Symptôme
L’erreur se produit typiquement dans une méthode qui tente de lever une exception spécifique à WooCommerce, par exemple lors de la validation d’un champ personnalisé sur une commande :
if ( empty( $numero_reference ) ) {
throw new WC_Data_Exception( 'reference_manquante', 'Le numéro de référence est requis.' );
}En local, ce code s’exécute sans problème. En production, la même ligne provoque une erreur fatale non interceptée, qui interrompt complètement l’exécution de la requête en cours, parfois en plein tunnel de commande.
Diagnostic
La classe WC_Data_Exception appartient au cœur de WooCommerce, pas à l’extension elle-même. En local, WooCommerce est généralement déjà actif et entièrement chargé au moment où l’extension s’exécute, ce qui masque totalement le problème. En production, l’ordre de chargement des extensions dépend de facteurs qui échappent au contrôle du développeur : ordre alphabétique des dossiers, activation manuelle successive, ou usage d’un outil de gestion d’extensions qui ne respecte pas l’ordre attendu.
Si l’extension personnalisée s’exécute avant que WooCommerce n’ait terminé de charger ses propres classes — par exemple parce qu’elle s’accroche à un hook déclenché trop tôt comme plugins_loaded avec une priorité insuffisamment tardive — la classe WC_Data_Exception n’existe tout simplement pas encore au moment de l’appel.
Un second facteur aggravant, spécifique à Composer, concerne l’autoload de l’extension elle-même : si le fichier composer.json déclare un espace de nom qui entre en collision avec une classe du cœur, ou si le dossier vendor n’est pas correctement régénéré après un ajout de dépendance, l’autoload de l’extension peut interférer avec la résolution normale des classes WooCommerce, provoquant une erreur similaire pour une raison différente.
Correctif
La correction la plus fiable consiste à ne jamais supposer que WooCommerce est chargé, et à le vérifier explicitement avant tout usage de ses classes :
add_action( 'plugins_loaded', function () {
if ( ! class_exists( 'WooCommerce' ) ) {
return;
}
add_action( 'woocommerce_checkout_process', 'valider_reference_commande' );
}, 20 );La priorité 20, supérieure à la priorité par défaut de 10, laisse le temps à WooCommerce de terminer son propre chargement avant que l’extension ne tente d’y accrocher sa logique. Ce simple ajustement suffit dans la grande majorité des cas rencontrés.
Si le problème persiste malgré cette vérification, il faut régénérer l’autoload Composer avec composer dump-autoload -o après avoir vérifié qu’aucune règle du fichier composer.json ne déclare un espace de nom en conflit avec le préfixe WC_ utilisé par WooCommerce.
Prévention
- Toujours vérifier
class_exists( 'WooCommerce' )avant tout accrochage de logique dépendante de ses classes. - Déclarer explicitement WooCommerce comme dépendance requise dans l’en-tête du plugin, via le champ
Requires Pluginsdisponible depuis WordPress 6.5, pour que WordPress refuse l’activation de l’extension si WooCommerce est absent. - Tester l’extension sur un environnement où l’ordre d’activation des plugins diffère volontairement de celui du poste de développement, afin de reproduire les conditions réelles de production.
Une extension qui suppose l’ordre de chargement d’une autre extension finit toujours par rencontrer un environnement où cette supposition est fausse.
En résumé
Ce message d’erreur ne révèle presque jamais un problème d’import Composer au sens strict, mais un problème d’ordre de chargement entre l’extension personnalisée et WooCommerce lui-même. La vérification explicite de la présence de la classe WooCommerce, associée à une priorité de hook suffisamment tardive, résout la quasi-totalité des cas rencontrés en production.
