Que faut-il montrer en premier à un développeur qui maîtrise WordPress mais découvre WooCommerce : les hooks, les templates, ou l’API REST ? La réponse qui fonctionne le mieux en agence n’est ni la plus intuitive, ni celle qu’on trouve en tête d’une documentation générale.
Après avoir accompagné plusieurs recrues sur ce chemin, un ordre précis s’est dégagé, avec des étapes volontairement séquentielles : chaque niveau attend d’être solide avant d’ouvrir le suivant, plutôt que de tout exposer en même temps sous prétexte de gagner du temps.
Étape 1 : comprendre l’objet commande sans jamais le modifier
La première semaine ne touche à aucune ligne de code de production. Elle consiste à explorer l’objet WC_Order en lecture seule, depuis un environnement de recette isolé : lister ses méthodes principales (get_total(), get_items(), get_status()), comprendre la différence entre une commande, une ligne de commande et un article de ligne, et surtout repérer où ces données sont réellement stockées selon le mode de stockage actif sur le site.
Cette phase paraît lente au départ, mais elle évite l’erreur la plus fréquente chez un développeur junior : manipuler l’objet commande comme un simple article WordPress, sans tenir compte de sa structure spécifique.
Étape 2 : les hooks avant tout le reste
Le deuxième palier introduit les hooks WooCommerce les plus courants : woocommerce_before_calculate_totals, woocommerce_checkout_create_order, woocommerce_order_status_changed. L’exercice type consiste à ajouter un champ personnalisé au tunnel de commande, puis à l’enregistrer comme méta de commande via update_meta_data() suivi d’un save().
add_action( 'woocommerce_checkout_create_order', function ( $order, $data ) {
if ( ! empty( $_POST['instructions_livraison'] ) ) {
$order->update_meta_data(
'instructions_livraison',
sanitize_textarea_field( wp_unslash( $_POST['instructions_livraison'] ) )
);
}
}, 10, 2 );
Cet exercice, volontairement simple, expose déjà plusieurs notions essentielles : l’ordre d’exécution des hooks, la nécessité de nettoyer les données utilisateur, et la différence entre modifier un objet en mémoire et le persister réellement en base.
Étape 3 : les templates et leur surcharge via un thème enfant
Le troisième palier aborde la surcharge de templates, en insistant sur un point souvent négligé : copier un template dans un thème enfant fige sa version, et une mise à jour de WooCommerce qui modifierait ce même template ne sera jamais répercutée automatiquement. Chaque copie de template doit donc être documentée et revue à chaque montée de version majeure de l’extension.
Étape 4 : l’API REST, seulement une fois les fondamentaux acquis
L’API REST WooCommerce n’apparaît qu’en quatrième position, une fois les hooks et les templates bien assimilés. La raison est simple : un développeur qui découvre l’API REST avant de comprendre le cycle de vie d’une commande a tendance à la traiter comme une simple façade CRUD, sans percevoir les effets de bord déclenchés par les hooks internes lors d’une création ou d’une modification via cette API.
- Créer une commande de test via une requête authentifiée par mot de passe d’application.
- Observer, dans les journaux, quels hooks se déclenchent réellement lors de cet appel.
- Comparer ce comportement avec une commande créée depuis le tunnel d’achat classique.
Étape 5 : l’autonomie encadrée sur la production
La dernière étape n’arrive qu’après plusieurs semaines : un accès en production, mais limité à des interventions à faible risque, revues systématiquement par un développeur senior avant mise en ligne. Toucher directement à une commande réelle en autonomie complète vient en tout dernier, une fois que les quatre étapes précédentes ont été validées sur un projet de recette.
Le réflexe le plus utile que nous transmettons n’est pas une compétence technique précise, mais une question systématique : « cette modification déclenche-t-elle un hook que je ne connais pas encore ? » Cette question évite plus d’incidents qu’un long cours théorique.
Ce que cet ordre évite
En inversant l’ordre, par exemple en commençant par l’API REST parce qu’elle semble plus moderne, on observe systématiquement les mêmes erreurs : des commandes créées sans passer par les hooks de calcul de taxe, des méta enregistrées sans passer par save(), ou des templates modifiés directement dans le dossier de l’extension plutôt que dans un thème enfant.
Notre verdict
Ce parcours en cinq paliers demande de la patience côté encadrement, mais il produit des développeurs qui comprennent pourquoi une commande se comporte d’une certaine façon, plutôt que des développeurs qui savent seulement où copier un extrait de code trouvé en ligne. Sur les recrues suivies selon cette méthode, l’autonomie réelle sur une commande en production est arrivée au bout d’environ six semaines, sans incident majeur imputable à une méconnaissance des hooks.
