Stored ID handling - Phase 1

[iamdharmesh]

Description of the Change

This PR introduces a new helper function, distributor_register_data, which enables developers to register stored data references, such as IDs stored in post meta, shortcodes, or block attributes and define custom pre-distribution and post-distribution callbacks to process these references.

Function Definition

distributor_register_data
This function registers a piece of data by providing details about its location and the callbacks needed to process it during distribution.

Parameters

• $data_name (string): The unique identifier for the data.
• $args (array): An array of parameters that describe:
  • location (string): Where the data is stored. Accepted values are 'post_meta' or 'post_content'.
  • attributes (array): Additional details depending on the location:
    • For post meta:
      • meta_key (string): The post meta key. (Required)
    • For shortcodes:
      • shortcode (string): The shortcode tag. (Required)
      • shortcode_attribute (string|array): The attribute(s) containing the data. (Required)
    • For blocks:
      • block_name (string): The block name. (Required)
      • block_attribute (string|array): The attribute(s) containing the data. (Required)
  • pre_distribute_cb (callable): A callback function that prepares the data on the source site before distribution. It should return extra data required for processing on the target site.
  • post_distribute_cb (callable): A callback function that processes the extra data on the target site and returns the updated ID to replace the source reference.

I have added detailed information on how this function works along with examples. You can view them here.

Note

• For the Classic editor, the post content is distributed in its rendered form. Therefore, shortcode data does not work as expected because the output of the shortcode is distributed instead of the shortcode tag. Let's discuss how we can handle this. I need feedback on this from someone who has a better understanding of this.
• This PR is Phase 1 of stored ID handling, which aims to add support for popular plugins like ACF and Gravity Forms in upcoming phases. However, to fully support these plugins, additional implementation will be required beyond this newly added helper function.

How to test the Change

You can find examples of data registration using the distributor_register_data function in the documentation and the e2e-test-plugin file. But please feel free to experiment on your own for something different.

1. Check out this PR branch on both the source and target WordPress sites.
2. Register data using distributor_register_data for specific stored IDs in functions.php or in a custom plugin.
3. Test with Post Meta:
   • Register a stored ID reference for post meta using distributor_register_data.
   • Distribute the post and verify that the references update correctly on the target site.
   • Test with different scenarios, such as multiple metadata entries under the same meta key.
4. Test with Shortcodes:
   • Register a stored ID reference for a shortcode using distributor_register_data.
   • Distribute the post and verify that the ID is replaced with the correct target site equivalent.
   • Test with different scenarios, such as passing multiple attributes under shortcode_attribute, to ensure everything works as expected.
5. Test with Block Attributes:
   • Register a stored ID reference for a block using distributor_register_data.
   • Distribute the post and verify that the correct ID is assigned on the target site.
   • Test with different scenarios, such as passing multiple attributes under block_attribute, to ensure everything works as expected.

Changelog Entry

Added - The distributor_register_data function to handle stored ID references in post meta, shortcodes, and block attributes during distribution.

Credits

Props @dkotter, @iamdharmesh

Checklist:

• I agree to follow this project's Code of Conduct.
• I have updated the documentation accordingly.
• I have added Critical Flows, Test Cases, and/or End-to-End Tests to cover my change.
• All new and existing tests pass.

[iamdharmesh]

E2E tests with WP trunk are failing due to an issue in insertBlock command with WP 6.8. It will be resolved with this PR

[dkotter]

I didn't do a super thorough test of everything here but overall code looks good to me and the tests I have done also look good. Since this is just phase 1 of a larger effort, I'd love to see this get merged in so we can work on the next piece

[dkotter]

@peterwilsoncc Dharmesh mentioned you may want to review / have already reviewed this PR and may have some feedback to provide. If you get a chance to add that feedback, that would be great so we can get this merged and start progress on phase 2 of this feature

[peterwilsoncc]

Added a few notes, as discussed they're mainly nitpicks.

[peterwilsoncc]

Thanks for the follow up, this looks good for merge.

[Sidsector9]

Re-approving only to enable merging.