How to make your plugin compatible with HPOS in WooCommerce

WooCommerce has introduced High-Performance Order Storage (HPOS) as a significant improvement in how orders are stored and managed in the database. HPOS replaces the structure based on wp_posts and wp_postmeta with custom tables, improving the speed and scalability of online stores. If your plugin interacts with WooCommerce orders, it is essential to update it to be compatible with HPOS.

Check if your plugin is compatible with HPOS

Before making any changes, you must confirm whether your plugin is already compatible with HPOS. To do this:

• Enable HPOS in WooCommerce (Settings > Advanced > Features > High-Performance Order Storage).
• Run tests to see if your plugin continues to function correctly.
• Check if your code directly uses wp_posts and  wp_postmeta to handle orders.

Use the WooCommerce API instead of direct queries

If your plugin performs direct database queries to retrieve orders, you need to replace them with the WooCommerce API. HPOS stores orders in separate tables (wc_ordersand wc_order_meta), so code like this:

<?php
$order = $wpdb->get_row("SELECT * FROM {$wpdb->prefix}posts WHERE ID = $order_id AND post_type = 'shop_order'");

should be replaced with:

<?php
$order = wc_get_order( $order_id );

This ensures compatibility with any order storage method WooCommerce implements in the future.

Properly access and save order metadata

If you are accessing order metadata using wp_postmeta, like in this example:

<?php
$meta_value = get_post_meta( $order_id, '_custom_meta_key', true );

you should change it to:

<?php
$order = wc_get_order( $order_id );
$meta_value = $order->get_meta('_custom_meta_key');

To save metadata in an order, instead of using update_post_meta, use:

<?php
$order = wc_get_order( $order_id );
$order->update_meta_data('_custom_meta_key', 'custom_value');
$order->save();

This ensures that the data is stored correctly regardless of whether HPOS is enabled or not.

Declare compatibility with HPOS

WooCommerce allows developers to indicate that their plugin is compatible with HPOS via the  plugin.php file. Add this line in the init hook or during your plugin’s loading process:

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

This informs WooCommerce that your plugin is HPOS-ready.

Test and debug

After implementing these changes:

• Enable HPOS and test all functionalities of your plugin.
• Use  Query Monitor or  WooCommerce Logger to detect potential errors.
• Ensure that there are no direct queries to  wp_posts related to orders.

Updating your plugin to be compatible with HPOS is a crucial step to ensure its performance and compatibility with future WooCommerce versions. By following these best practices, you ensure that your plugin continues to work smoothly and provides a better experience for users.