[wp-trac] [WordPress Trac] #59783: Block Hooks: Mark and document publicly available global functions as being Core-only internal functions.

[WordPress Trac]

#59783: Block Hooks: Mark and document publicly available global functions as being
Core-only internal functions.
----------------------------+---------------------
 Reporter:  hellofromTonya  |       Owner:  (none)
     Type:  defect (bug)    |      Status:  new
 Priority:  normal          |   Milestone:  6.4
Component:  Editor          |     Version:  trunk
 Severity:  normal          |  Resolution:
 Keywords:  has-patch       |     Focuses:  docs
----------------------------+---------------------

Comment (by gziolo):

 I just wanted to raise `traverse_and_serialize_blocks` is an improvement
 over what was available in WordPress core before. A good example is the
 deprecated in WP 6.4 `_inject_theme_attribute_in_block_template_content`
 method that was calling `parse_blocks` + `_flatten_blocks` and applying
 direct modifications to the internal in-memory block representation before
 serializing it back to HTML. In fact, it's also the same approach that
 Bernie used to implement Block Hooks in the Gutenberg plugin, example:

 https://github.com/WordPress/gutenberg/blob/6f46fe824ffe2053890a073213b49a3aea8ae772/lib/compat/wordpress-6.4
 /block-hooks.php#L252-L253

 `traverse_and_serialize_blocks` is an attempt to simplify that processing
 in WordPress core and to consolidate modifications necessary to the blocks
 serialized as HTML more formally. We didn't discuss opening this to
 extenders so marking it as private is a good middle ground for now.

 From my perspective, the biggest challenge is that these callbacks are
 passed down through recursive calls of `traverse_and_serialize_block` when
 processing also inner blocks. I'd be happy to discuss ideas on how we
 could refactor the existing code to use filters instead. The simplest way
 to approach it I can think of would be setting filters inside
 `traverse_and_serialize_blocks` so anyone could extend the functionality
 of callbacks:

 {{{#!php
 <?php
 function traverse_and_serialize_blocks( $blocks, $pre_callback = null,
 $post_callback = null ) {

     $pre_callback   = apply_filters( 'traverse_blocks_pre', $pre_callback
 );
     $post_callback = apply_filters( 'traverse_blocks_post', $post_callback
 );

     /// Function body continues...
 }
 }}}

 However, this way, you don't have access to additional information that we
 pass to block visitors, like the list of all hooked blocks (probably
 irrelevant for extenders), but the information about the processed
 template or block pattern might be helpful.

 I'm sure there are many alternative ways it could be refactored, so what I
 shared is more of a conversation starter. The most important question is
 whether this should be opened to extenders, knowing that we use the same
 processing every time we need to inject hooked blocks. Today, it's only
 for templates, template parts, and block patterns shipped with the theme,
 but we are about to apply the same mechanism to the templates and patterns
 modified by users and stored in the database.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/59783#comment:5>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform