Un client demande un ajout simple : afficher le numéro de téléphone du magasin dans l’e-mail de confirmation de commande. Le développeur pressé ouvre le dossier wp-content/plugins/woocommerce/templates/emails/, trouve le fichier customer-processing-order.php, l’édite directement, teste, ça marche, il passe au ticket suivant. Trois semaines plus tard, une mise à jour de sécurité de WooCommerce écrase le fichier, et le numéro de téléphone disparaît sans que personne ne comprenne pourquoi avant un moment de flottement en support client.
Ce scénario, très courant, illustre un antipattern classique : traiter les fichiers d’un plugin tiers comme s’ils appartenaient au projet. Ce billet explique pourquoi cette pratique casse systématiquement les mises à jour, et comment WooCommerce prévoit justement un mécanisme de surcharge propre pour éviter ce piège. Il ne couvre pas la création d’un tout nouveau type d’e-mail, uniquement la personnalisation de ceux qui existent déjà.
Ce qu’on voit sur le terrain
Le symptôme est presque toujours le même : un e-mail qui fonctionnait correctement se met soudainement à ressembler à l’e-mail par défaut, sans changement volontaire de configuration. En creusant, on retrouve invariablement un fichier édité à la main dans le dossier du plugin, ou pire, dans le dossier vendor généré par Composer et régénéré à chaque déploiement.
Pourquoi c’est un problème
WooCommerce considère son propre dossier templates/ comme faisant partie de son code source, au même titre que n’importe quel fichier PHP du plugin. À chaque mise à jour, ce dossier est intégralement remplacé, sans avertissement ni sauvegarde spécifique. Le problème ne se limite d’ailleurs pas aux templates : modifier directement une classe comme WC_Email_Customer_Processing_Order dans le cœur du plugin produit exactement le même résultat au prochain update.
Le vrai problème dépasse la simple perte de code : ce genre de modification échappe totalement au contrôle de version si elle n’est pas immédiatement committée, et surtout, elle rend le diagnostic impossible pour quiconque reprend le projet plus tard. Rien dans le thème, dans le plugin maison ni dans le suivi de version n’indique qu’une personnalisation existe quelque part dans le core.
Ce que WooCommerce prévoit pour ce cas précis
WooCommerce documente lui-même un mécanisme de surcharge des templates de mails via le thème actif (ou, mieux, un thème enfant) : il suffit de copier le fichier concerné dans wp-content/themes/mon-theme-enfant/woocommerce/emails/customer-processing-order.php, puis de le modifier à cet endroit. Le fichier copié n’est jamais touché par une mise à jour, puisqu’il ne se trouve plus dans le dossier du plugin.
mon-theme-enfant/
└── woocommerce/
└── emails/
├── customer-processing-order.php
└── email-header.phpPour un ajout ponctuel comme un numéro de téléphone, un simple hook suffit même sans copier le fichier entier :
add_action( 'woocommerce_email_before_order_table', 'ajouter_telephone_magasin', 20, 4 );
function ajouter_telephone_magasin( $order, $sent_to_admin, $plain_text, $email ) {
if ( 'customer_processing_order' !== $email->id ) {
return;
}
echo 'Une question ? Contactez-nous au 04 XX XX XX XX.
';
}Cette approche par hook reste préférable dès que la modification tient en quelques lignes : elle survit à toutes les mises à jour, y compris celles qui modifient la structure interne du template.
Quoi faire quand il faut aller plus loin
Pour des changements plus profonds — réorganiser des sections entières, changer la logique d’affichage —, la bonne approche consiste à créer une classe qui étend la classe WC_Email concernée et à la réenregistrer via le filtre woocommerce_email_classes :
add_filter( 'woocommerce_email_classes', function( $email_classes ) {
require_once __DIR__ . '/class-wc-email-customer-processing-order-perso.php';
$email_classes['WC_Email_Customer_Processing_Order'] = new WC_Email_Customer_Processing_Order_Perso();
return $email_classes;
} );Cette classe personnalisée peut alors surcharger n’importe quelle méthode du parent, y compris le chemin vers son propre fichier de template, tout en restant totalement indépendante du dossier du plugin WooCommerce.
Migrer une personnalisation existante
- Repérer chaque fichier core modifié via une comparaison avec une installation propre de WooCommerce.
- Copier ces fichiers dans le thème enfant, au bon chemin sous
woocommerce/emails/. - Réappliquer les modifications dans ces copies, en documentant chaque changement par un commentaire.
- Réinstaller une version propre du plugin WooCommerce pour confirmer qu’aucune trace de modification ne subsiste dans son dossier.
Une astuce de vérification rapide avant chaque montée de version : lancer un diff entre le dossier
woocommerceinstallé et une archive fraîchement téléchargée depuis WordPress.org. Le moindre écart signale une modification core à migrer d’urgence.
Ce qu’on ne traite pas ici
Créer un nouvel e-mail transactionnel entièrement inédit — par exemple une alerte de réapprovisionnement — suit une logique différente, avec l’enregistrement d’une classe WC_Email complète dès le départ plutôt qu’une surcharge d’un e-mail existant. Ce sujet mérite un traitement à part.
En résumé
Modifier directement les fichiers d’un plugin tiers, aussi tentant soit-il pour un correctif rapide, revient à programmer sa propre régression à la prochaine mise à jour. WooCommerce fournit un mécanisme de surcharge propre par le thème, et un système de filtres pour aller plus loin sans jamais toucher au code source du plugin. Le coût initial — chercher le bon hook ou copier le bon fichier — reste toujours inférieur au coût de la régression silencieuse qu’il permet d’éviter.
