Blocks: Add post-block callback arg to `traverse_and_serialize_block(s)`, change signature

[Bernhard Reiter]

While working on #59399, I ​discovered that sibling block insertion wasn't likely going to work the way I had planned. As a consequence, I had to come up with a new way to make it work. This requires some changes to traverse_and_serialize_block(s).

Basically, we need to:

• Change the signature of the existing callback such that:
  • the function arguments are a reference to the current block (so it can be modified inline, which is important e.g. for theme attribute insertion), the parent block, and the previous block (instead of the block index and chunk index);
  • the return value is a string that will be prepended to the result of the inner block traversal and serialization.
• Add a second callback argument to traverse_and_serialize_block, which is called _after_ the current inner block is traversed and serialized.
  • Its function arguments are a reference to the current block, the parent block, and the next block.

Its usage is demonstrated in ​PR 5261: The callback arguments are now sufficient to insert the serialized hooked blocks as strings, rather than via insert_inner_block, prepend_inner_block, or append_inner_block. (The latter -- which have been introduced only recently, in [56618] -- are thus going to be obsolete.)

Per ​https://github.com/WordPress/wordpress-develop/pull/5247#discussion_r1331151853, I realized that sibling block insertion wasn't likely going to work the way I had planned. As a consequence, I had to come up with a new way to make it work.

Basically, we:

• Change the signature of the existing callback such that:
  • the function arguments are now a _reference_ to the current block (so it can be modified inline, which is important e.g. for theme attribute insertion), the parent block, and the previous block (instead of the block index and chunk index)
  • the return value is now a string that will be prepended to the result of the inner block traversal and serialization.
• Add a second callback argument to traverse_and_serialize_block, which is called _after_ the current inner block is traversed and serialized.
  • Its function arguments are a reference to the current block, the parent block, and the next block.

Its usage is demonstrated in #5261: The callback arguments are now sufficient to insert the serialized hooked blocks as strings, rather than via insert_inner_block, prepend_inner block, or append_inner_block.

Trac ticket: https://core.trac.wordpress.org/ticket/59412

[Bernhard Reiter]

In 56634:

Blocks: Revert implementation of block insertion functions.

In [56618], three functions (insert_inner_block, prepend_inner_block, and append_inner_block) were introduced. They were meant to be used for insertion of hooked blocks; however, it was discovered that the original idea wouldn't work for sibling insertion. Instead, a different approach will be taken (see #59412), and these functions are no longer needed and can thus be removed.

Reverts [56618].
See #59412, #59385, #59313.

[Bernhard Reiter]

In 56644:

Blocks: Change traverse_and_serialize_block(s)'s callback signature.

During work on #59399, it was discovered that sibling block insertion wasn't likely going to work the way it was planned, which required devising an alternative solution. This new solution requires some changes to traverse_and_serialize_block(s):

• Change the signature of the existing callback such that:
  • the return value is a string that will be prepended to the result of the inner block traversal and serialization;
  • the function arguments are: a reference to the current block (so it can be modified inline, which is important e.g. for theme attribute insertion), the parent block, and the previous block (instead of the block index and chunk index).
• Add a second callback argument to traverse_and_serialize_block(s), which is called after the block is traversed and serialized.
  • Its function arguments are a reference to the current block, the parent block, and the next block.

Props gziolo.
Fixes #59412. See #59313.

Committed to Core in https://core.trac.wordpress.org/changeset/56644.

Both the $pre_ and $post_callback functions that are given as arguments to traverse_and_serialize_block(s) receive a reference to the current block as its first argument. However, while any changes that the "pre" callback makes to the block are actually respected during serialization, the same isn't true for the "post" callback: Any changes that it makes are only applied after the block has already been serialized. For applications like `#59412`, we probably want to change that.

## Testing instructions

The behavior is covered by the newly added unit test. You can verify that it fails on trunk by cherry-picking ​https://github.com/WordPress/wordpress-develop/pull/5525/commits/a8c66337d0e095be95155cc4efc739312e89abc6 there, and running npm run test:php -- --group=blocks.

Trac ticket: https://core.trac.wordpress.org/ticket/59669

Committed to Core trunk in https://core.trac.wordpress.org/changeset/56970.

Backported to the 6.4 branch in https://core.trac.wordpress.org/changeset/57043.