Add filter to allow modifying response *after* embedded data is adde

[loboyle]

The rest_post_dispatch is intended to be used for modifying responses, but the _embedded data is not yet available which limits the manipulations that can be done. It would be useful to have another filter that allows us to modify the final result being sent back, immediately before it's encoded and echoed.

For context, this is a problem for me in my wp-rest-jmespath plugin, which allows applying a JMESPath transform to a response to limit/rewrite the fields (see ​https://github.com/elyobo/wp-rest-jmespath/issues/1). It is possible to work around this limitation by adding a handler for rest_pre_serve_request and copying the logic that would embed the data (e.g.https://github.com/elyobo/wp-rest-jmespath/commit/887a638cc00c0d80a9425346e5e6d9439a096ee3) but this is a fragile workaround - any changes to the logic for processing and sending after rest_pre_serve_request would not be picked up by the plugin and so responses may end up differing unexpectedly.

[joehoyle]

I also had to do something similar in ​https://gist.github.com/joehoyle/12e37c293adf2bb0ea1b though I wasn't much duplicated code, so I don't think it was a bad solution.

[loboyle]

Yes, yours requires less duplicated code because for your use case you can avoid sending the response yourself and leave WP to do that (and the actual embedding). I need to copy the logic for sending the request (embed, json encode, check for encoding errors, check for jsonp callback, output) which is a bit more involved - still not massive, but definitely more fragile than having a final filter to allow modifying the result.

[jnylen0]

I think a rest_post_embed filter right in between $this->response_to_data and wp_json_encode is a good idea. We haven't needed this yet on WP.com, but we probably will.

This filter wouldn't work for Joe's example of adding granularity to embeds. This should be handled in core instead, though - see #35613.

See also #38131 regarding excluding specific fields from responses.

[loboyle]

Yes, that would suit perfectly, thanks. Filtering responses (e.g. as discussed in #38131) is why I put together my plugin, JMESPath allows a very powerful and flexible way of processing responses - not just about response size by dropping fields, but additional filtering, renaming, combining etc as well.

[jnylen0]

Added a rest_post_embed filter in 38964.diff​. This will address the case described in this ticket. See #41159 for an additional, semi-related enhancement.

[jnylen0]

In 38964.2.diff​, changes per Slack feedback from @pento:

• Rename to rest_pre_echo_response - rest_post_embed isn't the best name as this filter will be run even if no embedded requests are inserted
• Fix documentation of $result parameter - at this point this is just a data array, not a WP_REST_Response object

[loboyle]

Great, thanks @jnylen0.

[jnylen0]

In 40961:

REST API: Add a filter to allow modifying the response *after* embedded data is added.

Fixes #38964.

[jnylen0]

Reopening for backport to 4.8 branch.

[westonruter]

In 41093:

REST API: Add a filter to allow modifying the response *after* embedded data is added.

Merges [40961] onto 4.8 branch.
Props jnylen0.
Fixes #38964 for 4.8.1.