UX improvements for HPOS CLI cleanup tool (#45322)

* When order is out of sync, suggest a fix

* Allow cleanup tool to remove data for placeholders even if order can’t be loaded from HPOS

* Prevent infinite loops in cleanup tool

* Add changelog

* Fix PHPCS violations

* Improve error messages

* Fix syntax error

* Minor fix

plugins/woocommerce/changelog/fix-44002

@@ -0,0 +1,4 @@
+Significance: patch
+Type: enhancement
+
+Various UX improvements in HPOS CLI cleanup tool.

plugins/woocommerce/src/Database/Migrations/CustomOrderTable/CLIRunner.php

@@ -938,14 +938,22 @@ ORDER BY $meta_table.order_id ASC, $meta_table.meta_key ASC;
 			return;
 		}
 
-		$progress = WP_CLI\Utils\make_progress_bar( __( 'HPOS cleanup', 'woocommerce' ), $order_count );
-		$count    = 0;
+		$progress   = WP_CLI\Utils\make_progress_bar( __( 'HPOS cleanup', 'woocommerce' ), $order_count );
+		$count      = 0;
+		$failed_ids = array();
 
 		// translators: %d is the number of orders to clean up.
 		WP_CLI::log( sprintf( _n( 'Starting cleanup for %d order...', 'Starting cleanup for %d orders...', $order_count, 'woocommerce' ), $order_count ) );
 
 		do {
-			$order_ids = $handler->get_orders_for_cleanup( $q_order_ids, $q_limit );
+			$failed_ids_in_batch = array();
+			$order_ids           = $handler->get_orders_for_cleanup( $q_order_ids, $q_limit );
+
+			if ( $failed_ids && empty( array_diff( $order_ids, $failed_ids ) ) ) {
+				break;
+			}
+
+			$order_ids = array_diff( $order_ids, $failed_ids ); // Do not reattempt IDs that have already failed.
 
 			foreach ( $order_ids as $order_id ) {
 				try {
@@ -957,18 +965,36 @@ ORDER BY $meta_table.order_id ASC, $meta_table.meta_key ASC;
 				} catch ( \Exception $e ) {
 					// translators: %1$d is an order ID, %2$s is an error message.
 					WP_CLI::warning( sprintf( __( 'An error occurred while cleaning up order %1$d: %2$s', 'woocommerce' ), $order_id, $e->getMessage() ) );
+					$failed_ids_in_batch[] = $order_id;
 				}
 
 				$progress->tick();
 			}
 
+			$failed_ids = array_merge( $failed_ids, $failed_ids_in_batch );
+
 			if ( ! $all_orders ) {
 				break;
 			}
+
+			if ( $failed_ids_in_batch && ! array_diff( $order_ids, $failed_ids_in_batch ) ) {
+				WP_CLI::warning( __( 'Failed to clean up all orders in a batch. Aborting.', 'woocommerce' ) );
+				break;
+			}
 		} while ( $order_ids );
 
 		$progress->finish();
 
+		if ( $failed_ids ) {
+			return WP_CLI::error(
+				sprintf(
+					// translators: %d is the number of orders that were cleaned up.
+					_n( 'Cleanup completed for %d order. Review errors above.', 'Cleanup completed for %d orders. Review errors above.', $count, 'woocommerce' ),
+					$count
+				)
+			);
+		}
+
 		WP_CLI::success(
 			sprintf(
 				// translators: %d is the number of orders that were cleaned up.

plugins/woocommerce/src/Internal/DataStores/Orders/LegacyDataHandler.php

@@ -153,21 +153,26 @@ class LegacyDataHandler {
 	public function cleanup_post_data( int $order_id, bool $skip_checks = false ): void {
 		global $wpdb;
 
-		$order = wc_get_order( $order_id );
-		if ( ! $order ) {
-			// translators: %d is an order ID.
-			throw new \Exception( esc_html( sprintf( __( '%d is not a valid order ID.', 'woocommerce' ), $order_id ) ) );
-		}
+		$post_is_placeholder = get_post_type( $order_id ) === $this->data_synchronizer::PLACEHOLDER_ORDER_POST_TYPE;
+		if ( ! $post_is_placeholder ) {
+			$order = wc_get_order( $order_id );
 
-		if ( ! $skip_checks && ! $this->is_order_newer_than_post( $order ) ) {
-			throw new \Exception( esc_html( sprintf( __( 'Data in posts table appears to be more recent than in HPOS tables.', 'woocommerce' ) ) ) );
+			if ( ! $order ) {
+				// translators: %d is an order ID.
+				throw new \Exception( esc_html( sprintf( __( '%d is not a valid order ID.', 'woocommerce' ), $order_id ) ) );
+			}
+
+			if ( ! $skip_checks && ! $this->is_order_newer_than_post( $order ) ) {
+				// translators: %1 is an order ID.
+				throw new \Exception( esc_html( sprintf( __( 'Data in posts table appears to be more recent than in HPOS tables. Compare order data with `wp wc hpos diff %1$d` and use `wp wc hpos backfill %1$d --from=posts --to=hpos` to fix.', 'woocommerce' ), $order_id ) ) );
+			}
 		}
 
 		// Delete all metadata.
 		$wpdb->query(
 			$wpdb->prepare(
 				"DELETE FROM {$wpdb->postmeta} WHERE post_id = %d",
-				$order->get_id()
+				$order_id
 			)
 		);
 
@@ -178,11 +183,11 @@ class LegacyDataHandler {
 				"UPDATE {$wpdb->posts} SET post_type = %s, post_status = %s WHERE ID = %d",
 				$this->data_synchronizer::PLACEHOLDER_ORDER_POST_TYPE,
 				'draft',
-				$order->get_id()
+				$order_id
 			)
 		);
 
-		clean_post_cache( $order->get_id() );
+		clean_post_cache( $order_id );
 	}
 
 	/**