Lesson 1.3. HPOS

Friday, 9:15 AM

Yesterday the client enabled HPOS: WooCommerce recommends it, orders open faster. Today couriers didn't get a single address. The delivery plugin reads get_post_meta( $order_id, '_delivery_slot', true ), and orders are no longer in wp_posts.

The plugin had worked for three years, and nobody changed a single line in it.

Goal

After the lesson you write code that works both with and without HPOS, declare your plugin's compatibility and know how to move a store to the new tables safely.

Key concepts

  • HPOS (High-Performance Order Storage) — orders in dedicated tables instead of wp_posts
  • The default on new sites since WooCommerce 8.2; existing stores switch manually
  • Sync mode (compatibility mode): data is written to both storages during the transition
  • Declaring plugin compatibility: FeaturesUtil::declare_compatibility( 'custom_order_tables', ... )
  • OrderUtil::custom_orders_table_usage_is_enabled() — checks which storage is active
  • The orders screen changes: admin.php?page=wc-orders instead of edit.php?post_type=shop_order

Diagram

flowchart TB
  A["Existing store<br/>wp_posts"] --> B["Enable sync"]
  B --> C["Background migration<br/>wp wc hpos sync"]
  C --> D["Verify<br/>wp wc hpos verify_cot_data"]
  D --> E["HPOS as primary storage"]
  E --> F["Disable sync<br/>after testing"]

Code

Declaring compatibility in the main plugin file:

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

An orders list column for both screens:

PHP
<?php
use Automattic\WooCommerce\Utilities\OrderUtil;

$screen = OrderUtil::custom_orders_table_usage_is_enabled()
	? 'woocommerce_page_wc-orders'
	: 'edit-shop_order';

add_filter( "manage_{$screen}_columns", static function ( array $columns ): array {
	$columns['erp_id'] = __( 'ERP ID', 'my-plugin' );
	return $columns;
} );

// HPOS passes the order object, the legacy screen passes the post ID.
add_action( 'manage_woocommerce_page_wc-orders_custom_column', 'my_render_erp_column', 10, 2 );
add_action( 'manage_shop_order_posts_custom_column', 'my_render_erp_column', 10, 2 );

function my_render_erp_column( string $column, $order_or_id ): void {
	if ( 'erp_id' !== $column ) {
		return;
	}
	$order = $order_or_id instanceof WC_Order ? $order_or_id : wc_get_order( $order_or_id );
	echo esc_html( $order ? $order->get_meta( '_erp_id' ) : '' );
}

Common mistakes

SymptomCauseFix
The plugin is marked incompatible in WooCommerce → Settings → Advanced → FeaturesNo declare_compatibilityDeclare compatibility after reviewing the code
A column disappeared after HPOS was enabledHooks only for edit-shop_orderHook into both screens
An SQL report shows zerosA direct query to wp_posts with post_type = shop_orderwc_get_orders() or a query to the HPOS tables that checks the mode

Weak and strong answer

Question: What do you need to do to make a plugin support HPOS?

Weak answer. Add declare_compatibility to the plugin.

Strong answer. First remove direct access to orders: get_post_meta, WP_Query on shop_order, SQL against wp_posts. Replace it with wc_get_order(), wc_get_orders() and CRUD meta. Adapt the admin screen hooks. Test with and without HPOS, and only then declare compatibility.

Why the second is stronger: The declaration is the result of testing, not compatibility itself. The candidate knows what exactly breaks.

Practice

Rewrite the delivery plugin from the start of the lesson: remove get_post_meta and WP_Query on shop_order, read orders via wc_get_order() / wc_get_orders() and add declare_compatibility. Run it in the IDE below.

Then do the same with your own plugin and test it in both modes: with and without HPOS.

TEXT

Interview Questions

Orders get their own tables with the needed columns and indexes (status, date, customer, total). No thousands of wp_postmeta rows per order and no heavy JOINs. Order search and reports don't compete with posts and pages.

During the transition WooCommerce writes orders to both storages. You can roll back, and old plugins that read wp_posts still get data. After the transition sync is turned off because it doubles every write.

\Automattic\WooCommerce\Utilities\OrderUtil::custom_orders_table_usage_is_enabled().

Save your progress

Sign in or create a free account to mark lessons as completed and continue the whole course. You will come back to this lesson.