Block API: Add pre_render and post_render block filters

[dmsnell]

There are numerous needs to process posts at the block level without
demanding that plugin authors implement their own parsing systems.
Some needs involve structural processing - knowing the block type or
specific attributes on the block - while others are simply needing to
process the output HTML from a given block.

In this patch I'm adding an API to allow extending do_blocks
and gutenberg_render_block with a pre-processing and a
post-processing filter.

The main distinction between pre and post filtering is that pre
filtering gives us the chance to control or change how a block is rendered
while the post filtering gives us a chance to change a block's output.

One use case is in #8760 where we want to replace the HTML parts of
blocks while preserving other structure. Another use case could be
removing specific inner blocks or content based on the current user
requesting a post.

See the docblock comments in the patch itself for examples.

[dmsnell]

Rebased and restarted - previous head was 1014389

[aduth]

All filters must be documented:

https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#4-hooks-actions-and-filters

Which would be particularly helpful here because it's not clear to me the purpose in testing for null, or what the use-case is for pre_render.

I might have seen it as something of an inverse where a non-null filtered value would be inferred as the overridden value, similar to what's done in WP_oEmbed::get_html:

https://github.com/WordPress/WordPress/blob/da7a80d67fea29c2badfc538bfc01c8a585f0cbe/wp-includes/class-oembed.php#L375-L394

[dmsnell]

thanks @aduth - I'm not ready to document them because I'm not sure what I would document. trying to figure out the interface first 😉

I'll make the description in the PR clearer

[pento]

Hah, I was just thinking about something along the same line as a solution for #11704.

As @aduth mentioned, the usual method would be to call the filter pre_render_block, and to pass it a null value as the first argument. $block would then be passed as the second argument.

If the pre_render_block rendered a non-null value (including an empty string, as #11704 would do), render_block() would return that value, instead of running the rest of the function.

[dmsnell]

documented!

[aduth]

Been thinking on the naming / behavior of the filters added here, considering alignment with similar filtering elsewhere in core.

For "pre":

• In my prior comment, I noted these are sometimes used to short-circuit continued execution of a function (example). I could see this being a valid use case where someone would want to preempt the rendering of the block with their own substitution markup, not just altering attributes of the block. This is still technically achievable via the "post" filter, but only after the render callback has already been called.
• But there's also precedent for merely "prepare a value before it's used" (example), more like what's done here.
  • Minor, but the distinctly named $source_block and $block caught me off guard, where in most filtering I've seen the assignment occurs to the value being filtered (i.e. just have $block).

For "post":

• If its purpose is to alter the return value of the function, I would expect its name should more or less align to the name of the function
  • ...as I went to seek out examples, I notice this has already been added to core with the 'render_block' filter name?

To the last point, I'm a bit more curious the workflow for changes like this moving forward; whether they ought to be submitted as a pull request to the plugin, or as a proposal in a Trac issue for core.

[dmsnell]

Thanks @aduth for the comments here. On pre_ and post_ I am flexible on the terms but specifically what I think they need to communicate is that the pre_ filter has the ability to influence how something renders while the post_ filter has the ability to filter something after it has rendered.

The difference is in doing something like swapping out one block type for another or selecting a specific attribute (such as a locale) or filtering the list of child blocks vs. doing something like running a text filter over the output or scanning for images to cache.

as I went to seek out examples, I notice this has already been added to core with the 'render_block' filter name

sadly the way I remember it is that this change was introduced in Trac and committed without feedback when these pre_ and post_ filters existed in the plugin repo first. I had raised concern at the time before the merge about the render_block filter but that's history now. it has been my hope since before 5.0 that we could quickly deprecate and remove render_block since it doesn't communicate much about what or how it's filtering block data.

[pento]

As this is all in Core now, it should really be done on Trac.

The render_block filter in Core follows the same pattern as similar function/filter combinations. At the end of the function, a filter with the same name is applied to the return value.

The pre_* pattern has two usages, as @aduth noted. These broadly fall into two categories:

• The most common usage is to short-circuit the function. These are usually provided so that plugins can override the Core behaviour of that function.
• An older pattern, which we don't use anymore, is the style of filtering data something before it's processed, often for storing in the database. pre_update_option is one such example. The more common pattern for that now is function_name_data, so a filter on $block at the start of render_block would be render_block_data.

So anyway, there's a related core ticket (WP45451) that I've added a patch for pre_render_block and render_block_data filters on.

[aduth]

it has been my hope since before 5.0 that we could quickly deprecate and remove render_block since it doesn't communicate much about what or how it's filtering block data.

To me, it communicates well that it merely allows an opportunity to override what would otherwise be returned by the function, given the default return value.

[dmsnell]

Thanks for linking the Trac ticket @pento - I'll close this issue in favor of that one.