HPOS WooCommerce : problèmes fréquents avec le code personnalisé

Symptômes

• Les métadonnées de commande lues par le code sur mesure reviennent vides après l’activation de HPOS.
• Des colonnes, filtres ou meta boxes personnalisés manquent dans le nouvel écran des commandes.
• Les exports, rapports ou intégrations n’incluent plus les nouvelles commandes.
• Les valeurs enregistrées par le code sur mesure n’apparaissent pas sur la commande, ou disparaissent à l’enregistrement suivant.
• WooCommerce signale des extensions actives incompatibles et refuse de passer à HPOS.

Causes les plus fréquentes

Diagnostic

1. Vérifiez quel stockage fait autorité

WooCommerce → Réglages → Avancé → Fonctionnalités indique si les commandes sont stockées dans les tables HPOS ou dans les anciennes tables d’articles, et si le mode de compatibilité garde les deux synchronisés. Tant que la synchronisation est active, l’ancien code peut sembler fonctionner en lecture, ce qui masque le problème jusqu’à sa désactivation.

2. Cherchez dans le code

Cherchez dans le thème, les extensions sur mesure, les mu-plugins et les extensions de snippets :

$ grep -rnE "get_post_meta|update_post_meta|delete_post_meta|wp_insert_post|wp_update_post" wp-content/themes/my-theme wp-content/plugins/my-plugin
$ grep -rnE "shop_order|wp_posts|wp_postmeta|post_type *=" wp-content/themes/my-theme wp-content/plugins/my-plugin

Chaque résultat demande une décision : touche-t-il aux commandes ? Le code des produits et des pages n’est pas concerné.

3. Vérifiez les extensions

WooCommerce liste les extensions incompatibles sur l’écran des Fonctionnalités. Pour chacune, vérifiez si une mise à jour déclare la compatibilité ; sinon, interrogez l’éditeur ou prévoyez un remplacement.

4. Testez en préproduction avec la synchronisation activée, puis désactivée

Activez HPOS en préproduction avec le mode de compatibilité, déroulez les parcours critiques (checkout, notifications de paiement, e-mails, modifications dans l’administration, exports, intégrations), puis désactivez la synchronisation et recommencez. Du code qui ne fonctionne qu’avec la synchronisation activée n’est pas compatible.

Journaux et vérifications techniques

• L’écran des Fonctionnalités : stockage principal, état de la synchronisation, extensions incompatibles.
• WooCommerce → État → Journaux : fatal-errors après le changement de stockage.
• Notes et métadonnées des commandes de test, comparées avant et après le changement.
• Comparaisons en lecture seule d’une même commande dans les deux stockages tant que la synchronisation est active.

Solutions

Lisez et écrivez les commandes via l’API des commandes

// Lire
$order = wc_get_order( $order_id );
if ( ! $order ) {
    return;
}
$po_number = $order->get_meta( '_po_number' );

// Écrire : rien n’est enregistré avant l’appel à save()
$order->update_meta_data( '_po_number', sanitize_text_field( $value ) );
$order->save();

// Interroger
$orders = wc_get_orders( [
    'status'     => [ 'wc-processing' ],
    'limit'      => 50,
    'meta_query' => [
        [ 'key' => '_po_number', 'compare' => 'EXISTS' ],
    ],
] );

Prenez en charge les deux écrans d’administration

use Automattic\WooCommerce\Utilities\OrderUtil;

// Colonnes : ancien écran et écran HPOS
add_filter( 'manage_edit-shop_order_columns', 'myplugin_add_column' );
add_filter( 'manage_woocommerce_page_wc-orders_columns', 'myplugin_add_column' );

add_action( 'manage_shop_order_posts_custom_column', function ( $column, $post_id ) {
    myplugin_render_column( $column, wc_get_order( $post_id ) );
}, 10, 2 );
add_action( 'manage_woocommerce_page_wc-orders_custom_column', function ( $column, $order ) {
    myplugin_render_column( $column, $order );
}, 10, 2 );

// Meta box sur l’écran d’édition des commandes actif
add_action( 'add_meta_boxes', function () {
    add_meta_box( 'myplugin-box', 'Bon de commande', 'myplugin_render_box', wc_get_page_screen_id( 'shop-order' ), 'side' );
} );

function myplugin_render_box( $post_or_order ) {
    $order = $post_or_order instanceof WP_Post ? wc_get_order( $post_or_order->ID ) : $post_or_order;
    // …
}

Déclarez la compatibilité dans vos propres extensions

add_action( 'before_woocommerce_init', function () {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
    }
} );

Ce qu’il ne faut pas faire

• Ne déclarez pas la compatibilité pour faire taire l’avertissement avant d’avoir vérifié le code.
• Ne désactivez pas le mode de compatibilité juste après la bascule : gardez-le comme voie de retour arrière jusqu’à ce que la boutique ait fonctionné correctement un certain temps.
• Ne « réparez » pas les valeurs manquantes en copiant des métadonnées entre tables en SQL.

Quand faire appel à un expert

Faites appel à un ingénieur quand l’audit trouve des accès aux commandes dispersés dans de nombreux fichiers, quand une extension indispensable n’a pas de version compatible, quand les données de commande diffèrent déjà entre les stockages, ou quand la boutique est assez grande pour que la migration elle-même doive être planifiée.

Problèmes liés

• WooCommerce / Commandes Commandes WooCommerce manquantes ou incorrectes Avant de considérer une commande comme perdue, vérifiez tous les statuts, les brouillons et le prestataire de paiement. Les totaux faux viennent souvent des taxes, frais, codes promo ou recalculs. →
• WooCommerce / Erreurs Erreur fatale WooCommerce : guide de dépannage pratique Lisez correctement l’erreur fatale (fichier, ligne, trace) et rattachez-la au changement qui l’a déclenchée. →
• WooCommerce / Erreurs Conflit d’extensions WooCommerce : comment trouver la cause Partez des preuves (l’erreur, le moment, la requête) et isolez en préproduction par moitiés, pas extension par extension en production. →

Questions fréquentes