Chapitre 10.2 — Les hooks WooCommerce

⏱️ TL;DR — WooCommerce est extrêmement extensible grâce à des centaines de hooks (actions & filtres, Partie 5) : des hooks de template (positionner du contenu sur la fiche produit, le panier, le checkout) et des hooks de cycle de vie (commande créée, statut changé, paiement complété). On personnalise presque tout sans surcharger de template en se branchant au bon hook avec la bonne priorité. Connaître les hooks clés (et savoir les trouver) est la compétence centrale du dev WooCommerce.

🎯 Objectifs

• Utiliser les hooks de template pour placer/retirer du contenu.
• Réagir aux événements du cycle de commande.
• Trouver le bon hook (documentation, code, plugins d’inspection).
• Gérer les priorités et l’ordre d’affichage.

1. Deux familles de hooks

• Hooks de template : positionnés dans les templates Woo (woocommerce_before_single_product, woocommerce_after_shop_loop_item…) → ajouter/retirer des éléments d’affichage sans copier le template.
• Hooks de cycle de vie : déclenchés par la logique métier (woocommerce_new_order, woocommerce_order_status_completed, woocommerce_payment_complete…) → réagir (envoyer un e-mail, synchroniser un ERP, débloquer un accès).

2. Ajouter du contenu via un hook de template

Exemple : afficher un badge « Livraison offerte » sous le prix sur la fiche produit :

add_action( 'woocommerce_single_product_summary', 'wpr_badge_livraison', 25 );
function wpr_badge_livraison() {
    global $product;
    if ( $product && (float) $product->get_price() >= 50 ) {
        echo '<p class="badge-livraison">' . esc_html__( 'Livraison offerte', 'wpr' ) . '</p>';
    }
}

• woocommerce_single_product_summary est le hook du bloc résumé produit ; la priorité (25) place votre contenu après le prix (10) et avant le bouton (30).
• On utilise les priorités de Woo pour se positionner finement (les éléments natifs ont des priorités connues : titre 5, prix 10, extrait 20, add-to-cart 30, meta 40).

3. Retirer ou déplacer un élément natif

WooCommerce attache ses éléments via add_action — on peut donc les retirer :

// Retirer le résumé court sur la fiche produit
remove_action( 'woocommerce_single_product_summary', 'woocommerce_template_single_excerpt', 20 );
 
// Déplacer le prix après l'add-to-cart (retirer puis re-ajouter à une autre priorité)
remove_action( 'woocommerce_single_product_summary', 'woocommerce_template_single_price', 10 );
add_action( 'woocommerce_single_product_summary', 'woocommerce_template_single_price', 35 );

⚠️ Piège n°1 — la priorité au retrait. Pour remove_action, il faut la même priorité que lors de l’ajout (ch. 5.2). Retirer woocommerce_template_single_price sans indiquer 10 échoue silencieusement. Repérez la priorité d’origine (doc/code) avant de retirer/déplacer.

4. Réagir au cycle de commande

// Quand un paiement est confirmé
add_action( 'woocommerce_payment_complete', 'wpr_on_paiement', 10, 1 );
function wpr_on_paiement( $order_id ) {
    $order = wc_get_order( $order_id );
    // débloquer un accès, notifier un ERP, etc.
}
 
// Au passage d'une commande en "terminée"
add_action( 'woocommerce_order_status_completed', 'wpr_on_completed', 10, 1 );

Le cycle de statut d’une commande : pending → processing (payée, à traiter) → completed, avec on-hold, cancelled, refunded, failed. Choisir le bon hook de statut est crucial (ex. débloquer un accès sur payment_complete/processing, pas sur completed qui peut être manuel).

⚠️ Piège n°2 — le mauvais hook de statut. Débloquer un accès seulement sur order_status_completed peut retarder l’accès (certaines boutiques ne passent en « completed » que manuellement). Pour un produit numérique payé, woocommerce_payment_complete ou le passage en processing est souvent le bon moment. Comprenez le flux de statuts de la boutique concernée.

5. Trouver le bon hook

Avec des centaines de hooks, la compétence est de trouver le bon :

• Documentation WooCommerce (référence des hooks) et le code (les templates Woo montrent les do_action/apply_filters en contexte).
• Query Monitor (ch. 4.5) : onglet « Hooks & Actions » pour voir ce qui se déclenche sur une page.
• Des plugins d’inspection qui affichent les noms de hooks directement dans le rendu (fiche produit, checkout).
• Convention de nommage : woocommerce_before_… / woocommerce_after_… autour d’un élément, woocommerce_{objet}_{evenement} pour le cycle de vie.

💡 Pour un dev React — WooCommerce pousse à l’extrême la philosophie hooks = points d’extension (Partie 5) : chaque zone d’affichage et chaque étape du cycle est un événement auquel vous vous abonnez. C’est un système de plugins dans le plugin, comparable à une architecture riche en hooks/événements. Une fois le réflexe « quel hook pour ça ? » acquis, personnaliser WooCommerce devient mécanique — et c’est là que se trouve l’essentiel des missions.

✏️ Exercices

1. Vous voulez afficher un message personnalisé après le bouton « Ajouter au panier » sur la fiche produit. Quel type de hook, et comment gérer la position ?
2. Pour donner accès à un contenu dès que la commande est payée (produit numérique), quel hook choisir et pourquoi pas order_status_completed ?
3. Comment retirer un élément natif affiché par WooCommerce ?

🧠 Quiz de révision

Chapitre suivant : Personnaliser produits & checkout.