Rendre votre plugin WooCommerce compatible avec HPOS (High-Performance Order Storage)

HPOS accélère WooCommerce en stockant les commandes dans des tables dédiées. Vous gagnez en rapidité, en fiabilité et en scalabilité. Pour les nouvelles boutiques, HPOS est activé par défaut. Pour les sites plus anciens, vous pouvez l’activer en toute sécurité après vérification des extensions.

Dans cet article, je vous montre comment rendre votre plugin compatible avec HPOS. Vous verrez comment déclarer la compatibilité, utiliser l’API WooCommerce plutôt que les fonctions WordPress génériques et tester correctement. Enfin, je liste des pièges courants et des astuces de performance.

HPOS en deux minutes

• Les commandes ne vivent plus dans wp_posts/wp_postmeta.
• HPOS ajoute des tables dédiées aux commandes, adresses et index.
• Résultat : création de commande plus rapide et recherche d’ordre plus fluide.

1. Déclarez la compatibilité HPOS

Ajoutez la déclaration dans le fichier principal de votre plugin. C’est le signal officiel pour WooCommerce.

<?php
/**
 * Plugin Name: Mon Plugin — Compat HPOS
 * Description: Déclare la compatibilité HPOS pour WooCommerce.
 * Author: Vous
 * Version: 1.0.0
 *
 * @package MonPlugin
 */

use Automattic\\WooCommerce\\Utilities\\FeaturesUtil;

defined( 'ABSPATH' ) || exit;

/**
 * Déclare la compatibilité HPOS pour le plugin.
 *
 * @since 1.0.0
 * @return void
 */
function monplugin_declarer_compatibilite_hpos() : void {
    // Vérifie la disponibilité de la classe avant l'appel.
    if ( class_exists( FeaturesUtil::class ) ) {
        // Le troisième argument = true -> compatible ; false -> incompatible (affiche un avertissement aux admins).
        FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
    }
}
add_action( 'before_woocommerce_init', 'monplugin_declarer_compatibilite_hpos' );Code language: PHP (php)

2. Utilisez l’API WooCommerce (CRUD), pas les fonctions WP

N’utilisez pas get_post() ou get_post_meta() pour les commandes. Servez-vous des objets WC_Order et des méthodes WC_Data.

<?php
/**
 * Récupère et modifie une commande via l'API WooCommerce (compatible HPOS).
 *
 * @param int $order_id Identifiant de la commande.
 * @return void
 */
function monplugin_mettre_a_jour_commande( int $order_id ) : void {
    // Au lieu de get_post( $order_id ).
    $order = wc_get_order( $order_id ); // Retourne un objet WC_Order ou null.

    if ( ! $order instanceof WC_Order ) {
        return;
    }

    // Métadonnées : utiliser les méthodes WC_Data (HPOS-safe).
    $order->update_meta_data( '_monplugin_flag', 'yes' );
    $order->add_meta_data( '_monplugin_score', 95 );

    // Sauvegarde unique pour réduire les I/O (perf).
    $order->save();
}Code language: HTML, XML (xml)

Remplacements typiques :

• get_post_meta() → $order->get_meta( $key, true );
• update_post_meta() → $order->update_meta_data( $key, $value ); $order->save();
• add_post_meta() → $order->add_meta_data( $key, $value ); $order->save();
• delete_post_meta() → $order->delete_meta_data( $key ); $order->save();

3. Détectez si HPOS est actif quand c’est utile

La plupart du temps, vous n’en avez pas besoin. Cependant, si vous construisez une requête SQL optimisée ou un rapport custom, vous pouvez vérifier si HPOS est activé :

<?php
use Automattic\\WooCommerce\\Internal\\DataStores\\Orders\\Util\\OrderUtil;

/**
 * Vérifie si la boutique utilise les tables HPOS.
 *
 * @since 1.0.0
 * @return bool
 */
function monplugin_hpos_actif() : bool {
    // Vrai si HPOS est actif pour les commandes « shop_order ».
    return function_exists( 'wc_get_container' )
        && class_exists( OrderUtil::class )
        && OrderUtil::custom_orders_table_usage_is_enabled();
}Code language: HTML, XML (xml)

4. Évitez ces pièges courants

• Jointures directes sur wp_posts/wp_postmeta pour les commandes. Préférez l’API Woo.
• Sauvegardes répétées : regroupez vos ->save() pour limiter les I/O.
• Suppositions sur post_type=shop_order dans l’admin. Utilisez OrderUtil ou wc_get_order_types().
• Requêtes non indexées : sur de grosses bases de données, interrogez via l’API pour profiter des index HPOS.

5. UX admin : informez et sécurisez

Si votre plugin exige HPOS, affichez un admin_notice tant qu’il n’est pas actif. S’il n’est pas compatible, déclarez-le en false pour que WooCommerce avertisse l’admin et évite les mauvaises surprises.

<?php
/**
 * Affiche un avertissement si HPOS n'est pas actif mais conseillé par le plugin.
 *
 * @return void
 */
function monplugin_notice_hpos() : void {
    if ( ! current_user_can( 'manage_woocommerce' ) ) {
        return;
    }

    if ( ! function_exists( 'wc_get_container' ) ) {
        return;
    }

    if ( function_exists( 'monplugin_hpos_actif' ) && monplugin_hpos_actif() ) {
        return; // Tout va bien.
    }

    printf(
        '<div class="notice notice-warning"><p>%s</p></div>',
        esc_html__( 'Mon Plugin : activez High-Performance Order Storage (HPOS) pour de meilleures performances.', 'monplugin' )
    );
}
add_action( 'admin_notices', 'monplugin_notice_hpos' );Code language: HTML, XML (xml)

6. Plan de tests recommandé

• Création/édition de commandes (back‑office).
• Métadonnées lues/écrites par votre plugin.
• Tâches CRON, webhooks, états de commandes.
• Rapports, exports, pages front dépendantes des commandes.
• Compatibilité avec d’autres extensions « sensibles » (paiement, expédition).

7. Activer HPOS dans WooCommerce

Dans WooCommerce ⟶ Paramètres ⟶ Avancé ⟶ Fonctionnalités. Activez High‑Performance Order Storage et suivez l’assistant si proposé. Sur les nouvelles boutiques, c’est généralement actif par défaut.

FAQ éclair

HPOS, c’est quoi ?
Des tables de données dédiées aux commandes, pensées pour l’e-commerce. Vous gagnez en vitesse, fiabilité et simplicité.

Dois-je migrer mes données ?
WooCommerce gère la transition. Votre code doit surtout utiliser l’API WooCommerce.

Comment déclarer la compatibilité ?
Ajoutez FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true ) dans le fichier principal, à l’action before_woocommerce_init.

En conclusion, HPOS est la voie rapide pour WooCommerce. Déclarez la compatibilité, utilisez l’API Woo, testez avec HPOS activé et désactivé, et surveillez vos save(). Votre plugin restera performant et prêt pour la croissance.