[HPOS CLI] Add support for backfilling specific properties or metadata

[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:

In #44281 we introduced the wp wc hpos backfill command which allows backfilling an order from/to the HPOS or posts datastore, regardless of which datastore is currently active. This allows merchants to fix one off errors where some data might've been modified outside of the CRUD layer.

While this works ok, sometimes there might be a need to sync just some specific metadata or properties from/to either datastore instead of the whole order. This PR introduces --meta-keys and --props arguments to wp wc hpos backfill which do precisely that.
While ideally orders would be backfilled in their entirety, this at least provides a last resort for some possible tricky cases.

Closes #41910.

How to test the changes in this Pull Request:

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

1. Make sure HPOS is set as datastore in WC > Settings > Advanced > Features and also that sync (compatibility mode) is disabled.
   Note: It shouldn't really matter which datastore is set and we'll test syncing both ways, but this will make testing instructions more straightforward.
2. Make sure your site has at least one order with billing details. Take note of its ID.
3. Run wp wc cot sync to ensure that things are 100% synced between datastores.
4. Open the order from step 2 for editing:
   • Change its status to any status.
   • Change the billing first name to any value you like.
   • Add some metadata using the metadata metabox ("Custom Fields") and make a note of the "Name" you used for the field.
5. Run wp wc hpos diff <order_id> and confirm that the changes made above are listed as differences.
6. Run wp wc hpos backfill <order_id> --from=hpos --to=posts --props=billing_first_name to backfill the billing first name alone.
7. Run wp wc hpos diff <order_id> again and confirm that the status is no longer listed as being different. This proves that the --props arg limited the backfill to only that prop (leaving "status" and meta alone).
8. Let's add some metadata to the posts version with wp post meta update <order_id> my_posts_meta my_meta_value.
9. Run wp wc hpos diff <order_id> to confirm that the new meta is listed as a difference (with a value only on the 'post' side).
10. Let's migrate my_posts_meta from the post to the HPOS order by running wp wc hpos backfill <order_id> --from=posts --to=hpos --meta_keys=my_posts_meta. Run wp wc hpos diff <order_id> to confirm that this difference has now disappeared.
11. Now let's migrate the HPOS meta you added on step 4 by running wp wc hpos backfill <order_id> --from=posts --to=hpos --meta_keys=<meta_key>. Again, verify that the difference is gone with wp wc hpos diff <order_id>.
12. Finally, let's backfill a property (in this case, the status, which we've left alone thus far) from posts to HPOS: wp wc hpos backfill <order_id> --from=posts --to=hpos --props=status. Verify once more with wp wc hpos diff <order_id>.
13. Thank you for following such long testing instructions. You're a beautiful person 😸.

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: ba3bac2

Test 🧪	Passed ✅	Failed 🚨	Broken 🚧	Skipped ⏭️	Unknown ❔	Total 📊	Duration ⏱️
API Tests	259	0	0	2	0	261	0m 39s
E2E Tests	170	0	0	182	0	352	6m 58s

---

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]

I wonder if it could be beneficial here to add a last scenario where we re-enable sync and see that even if partial backfills happened in the meantime, sync still behaves as intended. What do you think? 🤔

[jorgeatorres]

Added in c7fa5fe.

[lsinger]

Is there ever a situation where we don't return true? If not -- should there be? Or will there be one in the future? If we only ever return true, having a return value feels a bit misleading, as a caller of the method might believe based on the return value that it can fail.

[jorgeatorres]

So this docblock was just copied over from the parent class, which does return a value based on whether the post was updated or not. That said, it's a bit misleading too since the metadata update could've failed (which in that case is actually all order data except status/date) and that's not taken into account.

Similarly, save_meta_data() doesn't tell us whether the meta was updated, so I'd say that right now we can't really tell whether the order was correctly updated or not, so the bool seems useless but we might eventually provided we make some adjustments elsewhere.

[lsinger]

For improving readability a bit, could we pull out the boolean value into its own variable (e.g., $should_save) that we then pass to apply_filters?

[jorgeatorres]

Done in 70a77f2.

[lsinger]

This tests as described and looks good to me -- very nice job. ☺️

I did leave a few comments, but I'd consider none of them blocking. Please handle them as you see fit and feel free to re-request a review if you prefer.

[Stojdza]

Thank you for following such long testing instructions. You're a beautiful person

Thank you for such detailed testing instructions 🙌