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

 Replying to [comment:2 Bernhard Reiter]:

 Thanks for the explanation!

 > `traverse_and_serialize_blocks()` (is similar) to PHP's data structure
 traversal functions, such as `array_filter()`, or, perhaps most similarly,
 [https://www.php.net/manual/en/function.array-map.php `array_map()`].

 Yes, you're right, I see that.

 > For a generic traversal tool like that, filters didn't seem like the
 right fit, much like one wouldn't want to add a filter before invoking
 `array_map` instead of passing a callback to it

 Right. Thinking this is more a question of "PHP built-in functions that
 use callbacks" vs. WordPress functions that use callbacks (filters).
 Broadly speaking a WP filter is a method to execute multiple (named)
 callbacks at approximately the same time. Nothing more. They are still
 callbacks but somewhat dynamic and with more functionality. The WP filters
 make it very convenient for plugins to "hook in" and change how the core
 code operates at many places. And this is not limited to just one plugin
 at a time. Another advantage is that these callbacks can also be removed.

 Unfortunately `array_map()` and similar cannot run multiple callbacks.
 They simply do not have that functionality. Well, that can be "fixed" in
 WP by something like this if it's ever needed (untested code):
 {{{
 function wp_array_map( $filter_name, $array ) {
     $array = array_map(
         function( $element ) use ( $filter_name ) {
             return apply_filters( $filter_name, $element );
         },
         $array
     );

     return $array;
 }
 }}}

 > It seems like the major qualm about `traverse_and_serialize_blocks()`
 using a callback argument (rather than a filter) is that people might the
 function multiple times with different callbacks, which will negatively
 impact performance, as traversal and serialization is a potentially costly
 operation

 Yep, this is one of the concerns if `traverse_and_serialize_blocks()` and
 friends are intended for use by extenders. Another is that using (static)
 callbacks for APIs that are intended to be used by plugins is not a good
 practice in WP. Filters are much more convenient and promote
 interoperability between (multiple) plugins and core.

 On the other hand if `traverse_and_serialize_blocks()` and friends are
 only intended for use by core code (as for now), it would be better to
 make them truly "private". In PHP there are several ways to do that,
 perhaps most common is to make them `private` methods of a `final` class.
 As @hellofromTonya mentioned on Slack, this seems like a better code
 design pattern for the requirements and I hope the existing functions can
 be deprecated in 6.5 and replaced with it.

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