Surcharger les templates WooCommerce dans un thème enfant sans casser les mises à jour

Un client demandait récemment de réorganiser complètement l’affichage de la fiche produit : galerie à droite, onglets déplacés au-dessus du prix, avis clients tout en bas dans un accordéon. Impossible d’obtenir ce résultat uniquement avec des hooks. C’est exactement le cas d’usage pour lequel WooCommerce prévoit un mécanisme de surcharge de templates, à condition de l’utiliser avec méthode plutôt qu’en copiant des fichiers au hasard.

La différence entre une surcharge bien faite et une bombe à retardement tient à trois choses : respecter l’arborescence exacte, ne modifier que ce qui est nécessaire, et surveiller les changements de version du plugin. Voici comment nous procédons sur chaque projet client qui en a besoin.

Comprendre le mécanisme de résolution des templates

WooCommerce charge ses templates via la fonction wc_get_template(), qui cherche d’abord un fichier correspondant dans le thème actif (ou le thème enfant), avant de retomber sur la version fournie par le plugin. L’ordre de recherche est précis :

1. votre-theme/woocommerce/nom-du-template.php
2. votre-theme/woocommerce/nom-du-template.php dans le thème parent si le thème actif est un thème enfant
3. wp-content/plugins/woocommerce/templates/nom-du-template.php en dernier recours

Le chemin doit reproduire exactement celui du plugin. Pour surcharger templates/single-product/price.php, le fichier doit être copié à l’identique dans votre-theme-enfant/woocommerce/single-product/price.php — un dossier mal nommé et la surcharge est silencieusement ignorée.

Copier un template proprement

La première étape consiste à repérer le fichier source dans wp-content/plugins/woocommerce/templates/, puis à le copier tel quel dans le thème enfant, sans rien changer avant d’avoir vérifié que l’affichage reste identique :

mkdir -p wp-content/themes/mon-theme-enfant/woocommerce/single-product
cp wp-content/plugins/woocommerce/templates/single-product/price.php \
   wp-content/themes/mon-theme-enfant/woocommerce/single-product/price.php

Chaque template WooCommerce commence par un commentaire indiquant sa version, par exemple @version 3.6.0. C’est cette ligne qu’il faut surveiller après chaque mise à jour du plugin : si le fichier source a changé de version depuis la copie, WooCommerce > État affiche un avertissement listant précisément les templates désynchronisés, avec la version attendue et la version présente dans le thème.

Modifier sans tout réécrire

Une fois copié, le fichier peut être adapté. Sur l’exemple de la galerie déplacée à droite, il ne s’agissait que de réordonner deux appels dans content-single-product.php :

<div class="produit-layout-inverse">
    <div class="colonne-resume">
        <?php do_action( 'woocommerce_single_product_summary' ); ?>
    </div>
    <div class="colonne-galerie">
        <?php do_action( 'woocommerce_before_single_product_summary' ); ?>
    </div>
</div>

La bonne pratique consiste à garder toutes les actions do_action d’origine intactes : elles conditionnent le fonctionnement d’autres extensions (avis, wishlist, cross-sell) qui s’y accrochent. Seule la structure HTML autour est réorganisée.

Quand éviter la surcharge de template

Toutes les personnalisations ne justifient pas une copie de fichier. Trois signaux doivent alerter :

• Si le besoin peut se résoudre avec un hook existant (ajout, masquage conditionnel, changement de texte), la surcharge est inutile et fragile.
• Si le template copié est volumineux et rarement modifié par les mises à jour de WooCommerce (comme archive-product.php), le risque de dérive est plus faible ; s’il est modifié fréquemment (comme les templates liés au paiement), le risque de conflit augmente.
• Pour les futurs thèmes à blocs, un concept encore expérimental porté par le plugin Gutenberg, WooCommerce Blocks prévoit un système de templates HTML distinct, qui serait géré via l’éditeur de site plutôt que par des fichiers PHP copiés.

Sur chaque audit de boutique existante, la première chose que nous vérifions est WooCommerce > État > Modèles surchargés. C’est souvent là que se cachent les bugs qui apparaissent « après une mise à jour sans rien avoir touché ».

Documenter les surcharges pour l’équipe

Un dossier woocommerce/ qui grossit sans documentation devient vite un mystère pour la personne qui reprendra le projet. Nous ajoutons systématiquement un commentaire en tête de chaque fichier surchargé, précisant la raison de la modification et la date :

<?php
/**
 * Surcharge : galerie déplacée à droite du résumé (demande client, avril 2020)
 * Original : woocommerce/templates/single-product/content-single-product.php
 * Version d'origine au moment de la copie : 3.6.0
 */

Ce simple réflexe fait gagner un temps considérable lors du prochain audit de compatibilité, surtout quand plusieurs développeurs se succèdent sur le même thème sur plusieurs années.

En résumé

Surcharger un template WooCommerce est parfaitement légitime quand la structure d’affichage elle-même doit changer, mais ce n’est jamais la première option à envisager. Respecter l’arborescence, garder les actions natives, surveiller les numéros de version et documenter chaque copie : ces quatre réflexes transforment une pratique risquée en un outil de personnalisation fiable, qui survit aux montées de version plutôt que de les redouter.