[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:  needs-patch     |     Focuses:  docs
----------------------------+---------------------

Comment (by Bernhard Reiter):

 FWIW, I couldn't think of the proper functions to compare this to during
 our earlier Slack convo with @azaozz, but I'd liken
 `traverse_and_serialize_blocks()` 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()`].

 Much like the latter, `traverse_and_serialize_blocks()` takes a data
 structure (in our case, a block tree), traverses it, and applies a
 callback to each element it finds.

 Granted, `traverse_and_serialize_blocks()` is somewhat more domain-
 specific at it is traversing a tree of ''blocks'' rather than a more
 generic data structure; but within the domain of blocks and block trees,
 its applications are arguably comparably wide-ranging as `array_map()` is
 for arrays.

 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 (and remembering to remove
 the filter afterwards!) While it's really only used inside of Core for
 now, it's conceivable that `traverse_and_serialize_blocks()` could be of
 some use to extenders.

 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, especially for large block trees. I'll just note that the same
 applies to `array_map()`; a simple way to avoid running it multiple times
 for different callbacks is to compose one function from all callbacks that
 need to be applied, and pass that as the argument. This is something we
 could also add to the function's PHPDoc, if needed.

 Anyway, if folks feel that it should be marked as `@access private` and
 documented to be Core use only, I'm happy to oblige. I'd be also happy if
 we could maybe at least avoid the `_` prefix :)

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