WC_Order en détail : l’objet central des commandes WooCommerce

Un développeur qui débute sur WooCommerce a souvent le réflexe de continuer à manipuler $post ou get_post_meta() comme il le ferait sur un article standard. C’est une erreur qui se paie tôt ou tard : WooCommerce encapsule toute la logique de commande dans une classe dédiée, WC_Order, et contourner cette abstraction casse la compatibilité avec les extensions, les hooks natifs et, plus grave encore, avec la façon dont WooCommerce stocke ces données en base.

Comprendre WC_Order en profondeur, c’est comprendre comment WooCommerce pense une commande : un ensemble de lignes d’articles, de lignes de frais, de lignes de taxes et de méta-données, le tout piloté par un statut. Ce billet n’aborde pas la façon dont ces données sont stockées en base : il se concentre sur l’objet lui-même, tel qu’on le manipule au quotidien.

Une classe qui hérite d’un socle commun

WC_Order hérite de WC_Abstract_Order, elle-même construite sur WC_Data, la classe abstraite partagée par les produits, les commandes et les coupons. Cet héritage explique pourquoi les mêmes réflexes s’appliquent partout : des getters et setters, une méthode save(), et un système de méta-données typées plutôt que du get_post_meta() brut.

Récupérer et lire une commande

On n’instancie jamais WC_Order directement avec new : la bonne pratique consiste à passer par la fabrique fournie par WooCommerce, qui retourne le bon type d’objet (une commande normale ou un remboursement, par exemple) :

$order = wc_get_order( $order_id );

if ( ! $order ) {
    return;
}

echo $order->get_status();
echo $order->get_total();
echo $order->get_billing_email();

Chaque propriété passe par un getter dédié : get_status(), get_total(), get_date_created(), get_customer_id(), get_payment_method(). Cette liste est longue, mais elle suit une convention stricte qui la rend prévisible une fois les premiers noms mémorisés.

Les lignes de commande : des objets à part entière

Une commande contient plusieurs types de lignes, chacune représentée par sa propre classe : WC_Order_Item_Product pour les articles, WC_Order_Item_Shipping pour la livraison, WC_Order_Item_Tax pour la taxe, WC_Order_Item_Fee pour les frais additionnels. On les parcourt via get_items() :

foreach ( $order->get_items() as $item_id => $item ) {
    $produit = $item->get_product();
    printf(
        '%s x%d — %s',
        $item->get_name(),
        $item->get_quantity(),
        wc_price( $item->get_total() )
    );
}

foreach ( $order->get_items( 'shipping' ) as $shipping_item ) {
    echo $shipping_item->get_method_title();
}

Modifier une commande : setters, puis save()

Contrairement à un update_post_meta() immédiat, WooCommerce sépare la modification en mémoire de la persistance en base. On appelle les setters, puis save() une seule fois à la fin :

$order->set_status( 'processing' );
$order->update_meta_data( '_reference_interne', 'CMD-2020-0342' );
$order->set_customer_note( 'Livraison en point relais demandée par le client.' );
$order->save();

Cette séparation permet à WooCommerce de ne déclencher les hooks de sauvegarde qu’une seule fois, même si plusieurs propriétés changent, plutôt que de multiplier les écritures en base à chaque setter.

Les hooks déclenchés à la sauvegarde

C’est souvent là que les développeurs se perdent : il existe plusieurs hooks proches, chacun avec un rôle précis.

• woocommerce_before_order_object_save se déclenche juste avant l’écriture, avec l’objet encore modifiable.
• woocommerce_order_object_updated_props liste précisément les propriétés qui ont changé.
• woocommerce_update_order et woocommerce_new_order se déclenchent après la sauvegarde, respectivement pour une mise à jour et une création.
• woocommerce_order_status_changed se déclenche spécifiquement lors d’un changement de statut, avec l’ancien et le nouveau statut en paramètres.

add_action( 'woocommerce_order_status_changed', function( $order_id, $ancien_statut, $nouveau_statut, $order ) {
    if ( 'processing' === $nouveau_statut ) {
        // Notifier l'entrepôt du passage en préparation.
    }
}, 10, 4 );

Pièges fréquents

Le piège le plus courant reste d’appeler get_post_meta( $order_id, '_ma_cle', true ) par habitude, alors que $order->get_meta( '_ma_cle' ) est l’équivalent correct et reste compatible quel que soit le mode de stockage choisi par la boutique. Un autre piège consiste à appeler save() à répétition dans une boucle, ce qui multiplie inutilement les écritures et les hooks déclenchés.

Une règle simple à transmettre à une équipe qui découvre l’objet : si une donnée se lit avec un getter, elle se modifie avec le setter correspondant, jamais directement en base.

Notion clé à retenir

WC_Order n’est pas un simple conteneur de données : c’est une API complète qui isole le développeur de la structure de stockage sous-jacente. Ce découplage est précisément ce qui permet à WooCommerce de faire évoluer son moteur de stockage sans casser le code des extensions qui respectent l’objet plutôt que la base de données brute. Maîtriser ses getters, ses setters et ses hooks de sauvegarde reste le socle indispensable avant d’aborder des sujets plus avancés comme la personnalisation des statuts ou des lignes de commande.