Add a filter to build_query_vars_from_query_block

[sunyatasattva]

What?

This PR adds a filter to the build_query_vars_from_query_block which is used to parse a WP_Query and pass it down the Query Loop block context.

Why?

This allows Query Loop block variations to hook into the query and possibly inject custom query parameters, enabling developers to support all kinds of custom queries and create powerful variations on the Query Loop block.

For an example on how this can be used to achieve this goal, see this PR: woocommerce/woocommerce-blocks#6812 (specifically, this filter is used here).

Paging @gziolo and @ntsekouras.

How?

The minimal change to enable this is to wrap the return value of the function in a filter.

Testing Instructions

1. Add a callback to your PHP code that hooks to this filter, e.g.

add_filter(
  'gutenberg_build_query_vars_from_query_block',
  function ( $query ) {
    $query[ 'offset' ] = 1;

    return $query;
 },
 10,
 1
);

2. Add multiple Query Loop blocks to your pages with different settings.
3. Save the page and go to the front-end.
4. Notice that all the blocks will render with your modified query (e.g. start from an offset of one, if the above is used).

A way to test the practical use of this change would be to use the above-mentioned PR to see how it could work. Or just pull from trunk on WooCommerce Blocks.

[gziolo]

@sunyatasattva, thank you for opening this PR. I see this filter applicable in many more cases. It would help to handle custom post types or even custom fields for existing REST API endpoints registered by plugins 👍🏻

The way to move forward with this PR would be to include the documentation for the hook like here in this repo:

gutenberg/packages/block-library/src/navigation/index.php

Lines 334 to 345 in 79dcf05

	/**
	* Filters the fallback experience for the Navigation block.
	*
	* Returning a falsey value will opt out of the fallback and cause the block not to render.
	* To customise the blocks provided return an array of blocks - these should be valid
	* children of the `core/navigation` block.
	*
	* @since 5.9.0
	*
	* @param array[] default fallback blocks provided by the default block mechanic.
	*/
	return apply_filters( 'block_core_navigation_render_fallback', $fallback_blocks );

or like here in WordPress core:

https://github.com/WordPress/wordpress-develop/blob/7f7d616d822b79c952cbd6a3046a6f6a8aa5a35e/src/wp-includes/blocks.php#L262-L269

We also need to settle on the name of the hook that is going to stay forever. It can't be prefixed with gutenberg_ and it can be shorter than the function name. You can check the existing WordPress hooks for inspiration at https://developer.wordpress.org/reference/hooks/.

We will also need to move the updated function from lib/compat/wordpress-6.0/blocks.php to lib/compat/wordpress-6.1/blocks.php to ensure it polyfills the functionality in the Gutenberg plugin correctly. Later, we will need to backport those changes to WordPress Core to land them in WordPress 6.1 (planned for November 1st).

[ntsekouras]

Thanks for the PR @sunyatasattva! Everything @gziolo said is great 😄

We also need to look into the editor side(related: #34201), but it can happen in a different PR.

[spacedmonkey]

Php docs are a must have.

[sunyatasattva]

Hello @gziolo thank you for your review. I pushed another commit, let's see if I've understood correctly:

1. The function has been completely moved from compat/wordpress-6.0 to compat/wordpress-6.1, not just duplicated with the new changes. Is that right?
2. I added the docs to the filter.
3. I've changed the name of the filter to query_block_query_vars.

The reasoning for my proposal on that name is that:

1. Filters are not named like verbs, but rather should be nouns.
2. They should represent what is output by the filter itself.
3. There are such names for other filters as query_vars or removable_query_args. It seemed to me that such a name could match those naming conventions.

Let me know what you think and if I did everything right.

[ntsekouras]

Thanks for iterating @sunyatasattva! 💯

[ntsekouras]

Interestingly enough this code from here was close to the 6.0 release and didn't land there, so we should have moved this file to compat/6.1 either way.. Good timing for this change 😄

[sunyatasattva]

@ntsekouras Feedback implemented, let me know if there is anything else that should be done 🙏

[ntsekouras]

Great work, thanks @sunyatasattva! This looks good to me! 💯

I'd appreciate a final look from @gziolo, but I think it's good to 🚢

[ntsekouras]

I think this is the key part of the comment. Anything already supported by the block should be done by the block. For example we have special handling for offset based the perPage and page attribute, and if someone would alter only the perPage from the filter, would end up with wrong offset in the pagination..

[sunyatasattva]

Yea, I see that. I guess that's the risk with many filters, right? Each developer needs to be responsible and see what kind of side effects they might be introducing…

[gziolo]

Awesome, thank you @sunyatasattva for bringing it to the finish line. Once, we have also the matching API in the editor, let's make sure it is documented in the Block Editor Handbook somewhere in the hooks section:

https://github.com/WordPress/gutenberg/tree/trunk/docs/reference-guides/filters

[gziolo]

@sunyatasattva, can you resolve conflicts in this branch. It looks like I landed changes added in exactly the same place and git has some trouble understanding those are different features and both should be there 😅