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

> Derrière chaque commande WooCommerce se cache un objet riche, doté de dizaines de méthodes. Tour d'horizon de WC_Order, de ses propriétés à ses hooks de sauvegarde.

- Auteur : Clément Hadrot
- Publié le : 2020-03-19
- Mis à jour le : 2020-03-19
- Catégorie : E-commerce
- URL : https://wpmoderne.dev.wordpress-developpement.fr/ecommerce/wc-order-en-detail-objet-central-commandes-woocommerce/

## L’essentiel

- WC_Order encapsule commande, client et lignes en un seul objet
- Chaque modification passe par des getters et setters dédiés
- save() déclenche des hooks exploitables sans toucher au core

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

> L'essentiel à retenir : WC_Order encapsule commande, client et lignes en un seul objet ; Chaque modification passe par des getters et setters dédiés ; save() déclenche des hooks exploitables sans toucher au core

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.