HPOS: High-Performance Order Storage

use Automattic\WooCommerce\Utilities\FeaturesUtil;

add_action(
	'before_woocommerce_init',
	static function () {
		if ( class_exists( FeaturesUtil::class ) ) {
			FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );   // false = incompatible
			FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
		}
	}
);

<?php
use Automattic\WooCommerce\Utilities\FeaturesUtil;

$mine = FeaturesUtil::get_compatible_features_for_plugin( 'pocket-coffee-hpos/pocket-coffee-hpos.php' );
echo 'declared compatible:   ', implode( ', ', $mine['compatible'] ), "\n";
echo 'declared incompatible: ', wp_json_encode( $mine['incompatible'] ), "\n";
echo 'features without a declaration: ', count( $mine['uncertain'] ), "\n";

$for_hpos = FeaturesUtil::get_compatible_plugins_for_feature( 'custom_order_tables' );
foreach ( $for_hpos as $state => $plugins ) {
	printf( "%-12s %d plugins\n", $state, count( $plugins ) );
}

$ok = FeaturesUtil::declare_compatibility( 'custom_order_tables', WP_PLUGIN_DIR . '/pocket-coffee-hpos/pocket-coffee-hpos.php', true );
echo 'declare_compatibility() after init: ', var_export( $ok, true ), "\n";
echo 'registered features: ', count( FeaturesUtil::get_features( true ) ), "\n";

declared compatible:   cart_checkout_blocks, custom_order_tables
declared incompatible: []
features without a declaration: 30
compatible   10 plugins
incompatible 0 plugins
uncertain    2 plugins
declare_compatibility() after init: false
registered features: 32

10 compatible plugins found:

  EC Hello
  Pocket Coffee Analytics
  Pocket Coffee Architecture
  Pocket Coffee CRUD
  Pocket Coffee Checkout Blocks
  Pocket Coffee HPOS
  Pocket Coffee Hooks
  Pocket Coffee Products
  Pocket Coffee REST API
  Pocket Coffee Settings

0 incompatible plugins found

0 uncertain plugins found

<?php
/**
 * Plugin Name:          Pocket Coffee HPOS
 * Description:          Gift note on orders, written for High-Performance Order Storage and legacy posts storage alike.
 * Version:              0.1.0
 * Requires at least:    7.0
 * Requires PHP:         7.4
 * Requires Plugins:     woocommerce
 * WC requires at least: 10.0
 * WC tested up to:      11.2
 * Text Domain:          pocket-coffee-hpos
 * License:              GPL-2.0-or-later
 *
 * @package PocketCoffee\Hpos
 */

defined( 'ABSPATH' ) || exit;

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

const POCKET_COFFEE_HPOS_GIFT_NOTE = '_pc_gift_note';

// 1. Tell WooCommerce this plugin works with HPOS (and with the Cart and Checkout blocks).
add_action(
	'before_woocommerce_init',
	static function () {
		if ( class_exists( FeaturesUtil::class ) ) {
			FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
			FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
		}
	}
);

/**
 * Stores the gift note on the order. update_meta_data() + save() works on both storages.
 *
 * @param WC_Order $order Order.
 * @param string   $note  Note typed by the customer.
 */
function pocket_coffee_hpos_set_gift_note( WC_Order $order, $note ) {
	$note = sanitize_textarea_field( $note );
	if ( '' === $note ) {
		$order->delete_meta_data( POCKET_COFFEE_HPOS_GIFT_NOTE );
	} else {
		$order->update_meta_data( POCKET_COFFEE_HPOS_GIFT_NOTE, $note );
	}
	$order->save();
}

// 2. Log "order placed" with the order number and total once the order is paid or accepted.
add_action(
	'woocommerce_order_status_processing',
	static function ( $order_id, $order ) {
		wc_get_logger()->info(
			sprintf( 'Order %s placed: %s %s', $order->get_order_number(), $order->get_total(), $order->get_currency() ),
			array( 'source' => 'pocket-coffee-hpos' )
		);
	},
	10,
	2
);

// 3. Meta box on the order edit screen: the screen id differs between storages.
add_action(
	'add_meta_boxes',
	static function () {
		add_meta_box(
			'pocket-coffee-gift-note',
			__( 'Gift note', 'pocket-coffee-hpos' ),
			'pocket_coffee_hpos_render_gift_note_box',
			OrderUtil::get_order_admin_screen(), // woocommerce_page_wc-orders with HPOS, shop_order without.
			'side',
			'default'
		);
	}
);

/**
 * Renders the meta box. The argument is a WP_Post on the legacy screen and a WC_Order on the HPOS screen.
 *
 * @param WP_Post|WC_Order $post_or_order_object The object WordPress or WooCommerce passes.
 */
function pocket_coffee_hpos_render_gift_note_box( $post_or_order_object ) {
	$order = OrderUtil::init_theorder_object( $post_or_order_object );
	if ( ! $order ) {
		return;
	}

	wp_nonce_field( 'pocket_coffee_gift_note', 'pocket_coffee_gift_note_nonce' );
	printf(
		'<textarea name="pocket_coffee_gift_note" rows="3" style="width:100%%">%s</textarea>',
		esc_textarea( (string) $order->get_meta( POCKET_COFFEE_HPOS_GIFT_NOTE ) )
	);
}

// 4. Save it. Both order edit screens fire this action with the order ID; the second argument
// is a WP_Post on the legacy screen and a WC_Order on the HPOS screen, so load the order by ID.
add_action(
	'woocommerce_process_shop_order_meta',
	static function ( $order_id ) {
		$nonce = isset( $_POST['pocket_coffee_gift_note_nonce'] ) ? sanitize_text_field( wp_unslash( $_POST['pocket_coffee_gift_note_nonce'] ) ) : '';
		$order = wc_get_order( $order_id );
		if ( ! $order || ! wp_verify_nonce( $nonce, 'pocket_coffee_gift_note' ) || ! isset( $_POST['pocket_coffee_gift_note'] ) ) {
			return;
		}
		pocket_coffee_hpos_set_gift_note( $order, wp_unslash( $_POST['pocket_coffee_gift_note'] ) ); // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- sanitized in the function.
	}
);

// 5. A "Gift" column in the order list: one pair of hooks per list screen.
add_filter(
	'woocommerce_shop_order_list_table_columns', // HPOS list table.
	'pocket_coffee_hpos_add_gift_column'
);
add_filter(
	'manage_edit-shop_order_columns', // Legacy posts list table.
	'pocket_coffee_hpos_add_gift_column'
);

/**
 * Adds the Gift column after the status column.
 *
 * @param array $columns Columns.
 * @return array
 */
function pocket_coffee_hpos_add_gift_column( $columns ) {
	$result = array();
	foreach ( $columns as $key => $label ) {
		$result[ $key ] = $label;
		if ( 'order_status' === $key ) {
			$result['pocket_coffee_gift'] = __( 'Gift', 'pocket-coffee-hpos' );
		}
	}
	return $result;
}

/**
 * Prints the cell for one order.
 *
 * @param string       $column Column id.
 * @param WC_Order|int $order  Order object (HPOS) or post ID (legacy).
 */
function pocket_coffee_hpos_render_gift_cell( $column, $order = null ) {
	if ( 'pocket_coffee_gift' !== $column ) {
		return;
	}
	$order = $order instanceof WC_Order ? $order : wc_get_order( $order ? $order : get_the_ID() );
	echo $order && $order->get_meta( POCKET_COFFEE_HPOS_GIFT_NOTE ) ? esc_html__( 'Yes', 'pocket-coffee-hpos' ) : '&ndash;';
}
add_action( 'woocommerce_shop_order_list_table_custom_column', 'pocket_coffee_hpos_render_gift_cell', 10, 2 );
add_action( 'manage_shop_order_posts_custom_column', 'pocket_coffee_hpos_render_gift_cell', 10, 2 );

/**
 * Counts orders per status with SQL, the one case where the storage matters.
 *
 * @return array<string,int> Status (with the wc- prefix) => count.
 */
function pocket_coffee_hpos_count_orders_by_status() {
	global $wpdb;

	if ( OrderUtil::custom_orders_table_usage_is_enabled() ) {
		$table = OrderUtil::get_table_for_orders(); // For example wp_wc_orders.
		$rows  = $wpdb->get_results( "SELECT status, COUNT(*) AS total FROM {$table} WHERE type = 'shop_order' GROUP BY status", ARRAY_A ); // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Table name comes from WooCommerce.
	} else {
		$rows = $wpdb->get_results( "SELECT post_status AS status, COUNT(*) AS total FROM {$wpdb->posts} WHERE post_type = 'shop_order' GROUP BY post_status", ARRAY_A );
	}

	return array_map( 'intval', wp_list_pluck( $rows, 'total', 'status' ) );
}

<?php
/**
 * Places a Pocket Coffee order with CRUD objects only: no post or postmeta function is involved.
 *
 * @package PocketCoffee\Hpos
 */

/**
 * Creates a processing order.
 *
 * @param array<int,int> $lines     Product or variation ID => quantity.
 * @param string         $email     Billing and shipping e-mail.
 * @param string         $gift_note Optional gift note.
 * @return int Order ID.
 */
function pocket_coffee_hpos_place_order( array $lines, $email, $gift_note = '' ) {
	$order = wc_create_order( array( 'status' => 'pending' ) );

	foreach ( $lines as $product_id => $quantity ) {
		$order->add_product( wc_get_product( $product_id ), $quantity );
	}

	$address = array(
		'first_name' => 'Ada',
		'last_name'  => 'Lovelace',
		'email'      => $email,
		'address_1'  => 'Calle de Alcala 1',
		'city'       => 'Madrid',
		'state'      => 'M',
		'postcode'   => '28014',
		'country'    => 'ES',
	);
	$order->set_address( $address, 'billing' );
	$order->set_address( $address, 'shipping' );
	$order->set_payment_method( 'bacs' );
	$order->calculate_totals();
	$order->save();

	if ( '' !== $gift_note ) {
		pocket_coffee_hpos_set_gift_note( $order, $gift_note );
	}

	$order->update_status( 'processing' ); // Saves the order and fires woocommerce_order_status_processing.

	return $order->get_id();
}

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

set_current_screen( 'dashboard' ); // Pretend to be in wp-admin: the screen helper throws outside it.
require_once WC_ABSPATH . 'includes/admin/wc-admin-functions.php';

$order = wc_get_orders( array( 'billing_email' => 'ada-hpos@example.test', 'limit' => 1 ) )[0];
$id    = $order->get_id();

echo 'order edit screen id:  ', OrderUtil::get_order_admin_screen(), "\n";
echo 'edit URL:              ', OrderUtil::get_order_admin_edit_url( $id ), "\n";

ob_start();
pocket_coffee_hpos_render_gift_note_box( $order );
$box = ob_get_clean();
echo 'meta box (WC_Order):    ', preg_replace( '/value="[^"]+"/', 'value="..."', $box ), "\n";

$_POST['pocket_coffee_gift_note_nonce'] = wp_create_nonce( 'pocket_coffee_gift_note' );
$_POST['pocket_coffee_gift_note']       = 'Happy birthday, Grace! Roasted on 2026-10-26.';
do_action( 'woocommerce_process_shop_order_meta', $id, $order );
echo 'saved through the hook: ', wc_get_order( $id )->get_meta( '_pc_gift_note' ), "\n";

$_POST = array( 'pocket_coffee_gift_note' => 'no nonce, must be ignored' );
do_action( 'woocommerce_process_shop_order_meta', $id, $order );
echo 'without a nonce:        ', wc_get_order( $id )->get_meta( '_pc_gift_note' ), "\n";

$columns = apply_filters( 'woocommerce_shop_order_list_table_columns', array( 'order_number' => 'Order', 'order_status' => 'Status', 'order_total' => 'Total' ) );
echo 'list columns:          ', implode( ', ', array_keys( $columns ) ), "\n";
ob_start();
do_action( 'woocommerce_shop_order_list_table_custom_column', 'pocket_coffee_gift', $order );
$cell = ob_get_clean();
echo 'gift cell:             ', $cell, "\n";

order edit screen id:  woocommerce_page_wc-orders
edit URL:              http://localhost:8081/wp-admin/admin.php?page=wc-orders&action=edit&id=438
meta box (WC_Order):    <input type="hidden" id="pocket_coffee_gift_note_nonce" name="pocket_coffee_gift_note_nonce" value="..." /><input type="hidden" name="_wp_http_referer" value="" /><textarea name="pocket_coffee_gift_note" rows="3" style="width:100%">written with update_meta_data()</textarea>
saved through the hook: Happy birthday, Grace! Roasted on 2026-10-26.
without a nonce:        Happy birthday, Grace! Roasted on 2026-10-26.
list columns:          order_number, order_status, pocket_coffee_gift, order_total
gift cell:             Yes

<?php
$order = wc_get_orders( array( 'billing_email' => 'ada-hpos@example.test', 'limit' => 1 ) )[0];
foreach ( glob( WC_LOG_DIR . 'pocket-coffee-hpos-*.log' ) as $file ) {
	foreach ( file( $file ) as $line ) {
		if ( false !== strpos( $line, 'Order ' . $order->get_id() . ' ' ) ) {
			echo preg_replace( '/^\S+ /', '', trim( $line ) ), "\n";
		}
	}
}

INFO Order 438 placed: 40.30 EUR

<?php
echo wp_json_encode( pocket_coffee_hpos_count_orders_by_status() ), "\n";
echo 'wc_get_orders( processing ): ', count( wc_get_orders( array( 'status' => 'processing', 'limit' => -1, 'return' => 'ids' ) ) ), "\n";

{"wc-cancelled":2,"wc-checkout-draft":13,"wc-completed":3,"wc-on-hold":18,"wc-processing":9}
wc_get_orders( processing ): 9

<?php
$ids = static fn( array $args ) => wp_json_encode( wc_get_orders( array_merge( $args, array( 'return' => 'ids', 'limit' => -1 ) ) ) );
$ada = array( 'billing_email' => 'ada-hpos@example.test' );

echo "--- the arguments every storage understands\n";
echo 'by email:           ', $ids( $ada ), "\n";
echo 'processing + email: ', $ids( array_merge( $ada, array( 'status' => 'processing' ) ) ), "\n";

echo "--- query types that need HPOS\n";
echo 'meta_query EXISTS:  ', $ids( array( 'meta_query' => array( array( 'key' => '_pc_gift_note', 'compare' => 'EXISTS' ) ), 'billing_email' => 'ada-hpos@example.test' ) ), "\n";
echo 'meta_query LIKE:    ', $ids( array( 'meta_query' => array( array( 'key' => '_pc_gift_note', 'value' => 'birthday', 'compare' => 'LIKE' ) ) ) ), "\n";
echo 'field_query OR:     ', $ids(
	array_merge(
		$ada,
		array(
			'field_query' => array(
				'relation' => 'OR',
				array( 'field' => 'total', 'value' => '30', 'compare' => '>=', 'type' => 'NUMERIC' ),
				array( 'field' => 'shipping_total', 'value' => '5', 'compare' => '<', 'type' => 'NUMERIC' ),
			),
		)
	)
), "\n";
echo 'date_query (paid):  ', $ids( array_merge( $ada, array( 'date_query' => array( array( 'column' => 'date_paid_gmt', 'after' => '1 hour ago' ) ) ) ) ), "\n";

echo "--- a custom argument\n";
add_filter(
	'woocommerce_order_query_args',
	static function ( $query_args ) {
		if ( ! empty( $query_args['has_gift_note'] ) ) {
			$query_args['meta_query'][] = array(
				'key'     => '_pc_gift_note',
				'compare' => 'EXISTS',
			);
		}
		unset( $query_args['has_gift_note'] );
		return $query_args;
	}
);
echo 'has_gift_note:      ', $ids( array_merge( $ada, array( 'has_gift_note' => true ) ) ), "\n";

echo "--- pagination\n";
$page = wc_get_orders( array_merge( $ada, array( 'limit' => 1, 'paginate' => true, 'return' => 'ids' ) ) );
printf( "total=%d pages=%d orders=%s\n", $page->total, $page->max_num_pages, wp_json_encode( $page->orders ) );

--- the arguments every storage understands
by email:           [438]
processing + email: [438]
--- query types that need HPOS
meta_query EXISTS:  [438]
meta_query LIKE:    [438]
field_query OR:     [438]
date_query (paid):  [438]
--- a custom argument
has_gift_note:      [438]
--- pagination
total=1 pages=1 orders=[438]

<?php
global $wpdb;
$order    = wc_get_orders( array( 'billing_email' => 'ada-hpos@example.test', 'limit' => 1 ) )[0];
$order_id = $order->get_id();

echo "=== book-era code, written for orders stored as posts\n";
echo '_order_total:          ', var_export( get_post_meta( $order_id, '_order_total', true ), true ), "\n";
echo '_billing_email:        ', var_export( get_post_meta( $order_id, '_billing_email', true ), true ), "\n";
echo 'post status:          ', get_post_status( $order_id ), "\n";
echo "get_posts() 'shop_order' for that e-mail: ", count(
	get_posts(
		array(
			'post_type'   => 'shop_order',
			'post_status' => 'any',
			'meta_key'    => '_billing_email',
			'meta_value'  => 'ada-hpos@example.test',
			'numberposts' => -1,
		)
	)
), " found\n";
echo 'SUM of _order_total in postmeta: ', var_export( $wpdb->get_var( "SELECT SUM(meta_value) FROM {$wpdb->postmeta} WHERE meta_key = '_order_total' AND post_id = {$order_id}" ), true ), "\n";

update_post_meta( $order_id, '_pc_gift_note', 'written with update_post_meta()' );
echo "after update_post_meta(): the order says '", wc_get_order( $order_id )->get_meta( '_pc_gift_note' ), "'\n";
delete_post_meta( $order_id, '_pc_gift_note' );

echo "\n=== a stale copy: the address fields were written to postmeta once, when the order was created\n";
$order = wc_get_order( $order_id );
$order->set_billing_city( 'Barcelona' );
$order->save();
echo "get_post_meta( id, '_billing_city' ): ", get_post_meta( $order_id, '_billing_city', true ), '   $order->get_billing_city(): ', wc_get_order( $order_id )->get_billing_city(), "\n";
$order->set_billing_city( 'Madrid' );
$order->save();

echo "\n=== the same questions with CRUD\n";
$order = wc_get_order( $order_id );
echo 'get_total():           ', $order->get_total(), "\n";
echo 'get_billing_email():   ', $order->get_billing_email(), "\n";
echo 'get_status():          ', $order->get_status(), "\n";
$found = wc_get_orders( array( 'billing_email' => 'ada-hpos@example.test', 'status' => 'processing', 'limit' => -1 ) );
echo 'wc_get_orders() count: ', count( $found ), "\n";
echo 'sum of totals:         ', array_sum( array_map( static fn( $o ) => (float) $o->get_total(), $found ) ), "\n";
$order->update_meta_data( '_pc_gift_note', 'written with update_meta_data()' );
$order->save();
echo 'after update_meta_data() + save(): ', wc_get_order( $order_id )->get_meta( '_pc_gift_note' ), "\n";

echo "\n=== magic properties of the 2.x era still answer; WooCommerce reports them with wc_doing_it_wrong()\n";
echo '$order->billing_email: ', $order->billing_email, '   $order->id: ', $order->id, "\n";

=== book-era code, written for orders stored as posts
_order_total:          ''
_billing_email:        'ada-hpos@example.test'
post status:          draft
get_posts() 'shop_order' for that e-mail: 0 found
SUM of _order_total in postmeta: NULL
after update_post_meta(): the order says 'Happy birthday, Grace!'

=== a stale copy: the address fields were written to postmeta once, when the order was created
get_post_meta( id, '_billing_city' ): Madrid   $order->get_billing_city(): Barcelona

=== the same questions with CRUD
get_total():           40.30
get_billing_email():   ada-hpos@example.test
get_status():          processing
wc_get_orders() count: 1
sum of totals:         40.3
after update_meta_data() + save(): written with update_meta_data()

=== magic properties of the 2.x era still answer; WooCommerce reports them with wc_doing_it_wrong()
$order->billing_email: ada-hpos@example.test   $order->id: 438

// Posts-era: every line below assumes that an order is a post.
add_action( 'add_meta_boxes', function () {
	add_meta_box( 'pc-gift', 'Gift note', 'pc_gift_box', 'shop_order', 'side' );
} );
function pc_gift_box( $post ) {
	echo '<textarea name="gift_note">' . esc_textarea( get_post_meta( $post->ID, '_pc_gift_note', true ) ) . '</textarea>';
}
add_action( 'save_post_shop_order', function ( $post_id ) {
	update_post_meta( $post_id, '_pc_gift_note', sanitize_text_field( $_POST['gift_note'] ) );
} );
add_filter( 'manage_edit-shop_order_columns', 'pc_gift_column' );
add_action( 'manage_shop_order_posts_custom_column', function ( $column, $post_id = 0 ) {
	if ( 'gift' === $column ) {
		echo get_post_meta( $post_id, '_pc_gift_note', true ) ? 'Yes' : '-';
	}
}, 10, 2 );
$gifts = get_posts( array( 'post_type' => 'shop_order', 'post_status' => 'wc-processing', 'meta_key' => '_pc_gift_note', 'numberposts' => -1 ) );

SUBCOMMANDS
  count_unmigrated
  disable
  enable
  migrate               [Deprecated] Use `wp wc hpos sync` instead.
  sync
  verify_cot_data

$ wp wc hpos status
HPOS enabled?: yes
Compatibility mode enabled?: no
Unsynced orders: 45
Orders subject to cleanup: 7

$ wp wc hpos count_unmigrated
There are 45 orders to be synced.

$ wp wc hpos diff 441
Warning: Differences found for order 441:
property                       hpos                        post
status                         processing                  draft
cart_tax                       0
total                          22.50                       0.00
payment_method                 bacs
customer_ip_address            127.0.0.1
customer_user_agent            WP CLI 2.12.0
version                        11.2.1
recorded_coupon_usage_counts   1
download_permissions_granted   1
order_key                      wc_order_8Ms5NbjLm1zEq
order_stock_reduced            1
date_paid                      2026-10-27T19:10:25+00:00
shipping_tax                   0
shipping_total                 0
discount_tax                   0
discount_total                 0
recorded_sales                 1
_billing_address_index         Ada Lovelace  Calle de Alcala 1  Madrid M 28014 ES ada-hpos2@example.test
_shipping_address_index        Ada Lovelace  Calle de Alcala 1  Madrid M 28014 ES
_pc_gift_note                  Second order
_shipping_email                                            ada-hpos2@example.test

$ wp wc hpos backfill 441 --from=hpos --to=posts
Success: Order 441 backfilled from hpos to posts.

$ wp wc hpos diff 441
Success: No differences found.

$ wp wc hpos verify_data --start-from=441 --end-at=441
Verification completed.
Success: 1 order was verified in 0 seconds.

$ wp wc hpos diff 441 --format=json
Success: No differences found.