Add HPOS CLI tool to compare an order between datastores

[jorgeatorres]

Submission Review Guidelines:

• I have followed the WooCommerce Contributing Guidelines and the WordPress Coding Standards.
• I have checked to ensure there aren't other open Pull Requests for the same update/change.
• I have reviewed my code for security best practices.
• Following the above guidelines will result in quick merges and clear and detailed feedback when appropriate.

Changes proposed in this Pull Request:

This PR adds a new CLI tool wp wc hpos diff which can be used to compare an order between datastores to see which properties or metadata differ. It's slightly more user friendly than wp wc verify_cot_data for individual orders.

This PR also adds a wp wc hpos status tool that displays current values of various HPOS variables, such as whether it is enabled or not, or how many orders need to be synced/etc.

Closes #41908.

How to test the changes in this Pull Request:

Using the WooCommerce Testing Instructions Guide, include your detailed testing instructions:

1. Make sure sync/compatibility mode is enabled on WC > Settings > Advanced > Features. Any datastore can be used.
2. Create a few orders (if needed).
3. Go to WC > Settings > Advanced > Features and disable compatibility mode.
4. Take note of the ID of any existing order.
5. Run wp wc hpos diff <order_id>. Output should be "Success: No differences found.".
6. Go to WC > Orders and make some changes to the order. For example, add some metadata or change any detail in the billing/shipping address.
7. Run wp wc hpos diff <order_id> again. This time the output should look something like this (depending on the changes made in the previous step):

   Warning: Differences found for order 8472:
   +------------------------+---------------------------+---------------------------+
   | property               | hpos                      | post                      |
   +------------------------+---------------------------+---------------------------+
   | date_modified          | 2024-01-01T11:13:34+00:00 | 2023-12-28T09:12:37+00:00 |
   | _billing_address_index | James Brown       US      |                           |
   | my_meta                | my_value                  |                           |
   +------------------------+---------------------------+---------------------------+
   

8. Now run wp wc cot sync to sync orders between datastores.
9. Run wp wc hpos diff <order_id> again and confirm, once more, that output is "Success: No differences found.".
10. Run wp wc hpos status to take a look at your HPOS variables. It should correctly reflect whether HPOS is enabled or not and other bits of information.

Changelog entry

• Automatically create a changelog entry from the details below.

Significance

• Patch
• Minor
• Major

Type

• Fix - Fixes an existing bug
• Add - Adds functionality
• Update - Update existing functionality
• Dev - Development related task
• Tweak - A minor adjustment to the codebase
• Performance - Address performance issues
• Enhancement - Improvement to existing functionality

Message

Comment

[github-actions]

Test Results Summary

Commit SHA: e12f483

Test 🧪	Passed ✅	Failed 🚨	Broken 🚧	Skipped ⏭️	Unknown ❔	Total 📊	Duration ⏱️
API Tests	259	0	0	2	0	261	0m 37s
E2E Tests	258	0	0	3	0	261	14m 2s

---

To view the full API test report, click here.
To view the full E2E test report, click here.
To view all test reports, visit the WooCommerce Test Reports Dashboard.

[github-actions]

Hi @lsinger,

Apart from reviewing the code changes, please make sure to review the testing instructions as well.

You can follow this guide to find out what good testing instructions should look like:
https://github.com/woocommerce/woocommerce/wiki/Writing-high-quality-testing-instructions

[lsinger]

Tests well -- a very nice and slick experience. Very cool!

Left a few notes, but no blockers in there. LGTM! 🚢

[lsinger]

We might want to add a note here why it's absolutely necessary to allow loose comparison.

[lsinger]

Interesting pattern! Could you explain why this was the best (only?) option here? Just for my personal understanding.

[jorgeatorres]

Given WC_Order is a WC_Data child class, the datastore in objects of this type has access protected so we can't directly change it from the outside.
To make things worse, that data_store variable is not directly an instance of the HPOS (or CPT) datastore, but of WC_Data_Store, which stores the details in a private variables.

WC_Data_Store is meant to be a singleton so what we could do here is add public methods to WC_Data to change its backing datastore, but that's not without its own set of problems (what happens when reading or saving data if you change the backing datastore in an object mid execution?) and I guess we don't want to increase API surface at this moment.

Now, even though datastores have a read() method that receives a "blank" object, this method's name is a bit misleading because this will not set the backing datastore on the blank object nor read all properties.
Metadata is read via $this->data_store->read_meta() which would use the "default" datastore unless we change it "somehow".

This ugly hack above is that "somehow" 😓. I believe the whole CRUD layer and datastore/object interactions in particular would benefit from a revision, but 🤷.

(Sorry if this is even more confusing)