Audit filters and actions

[danielbachhuber]

Let's make sure our controllers have a consistent pattern of filters and actions.

[peterigz]

It would be nice if the "get_items" controller function had a filter before returning back the response, passing in the $query and the array of items. This way you can add more data based on the query as a whole rather then just individual items (with "rest_prepare_" filter). For example when retrieving all the posts for a particular category, it would be good to get the archive title/description back with the data as well, plus other tags that are available outside of the loop.

It would also be good if the data structure was slightly different for returning multiple items as well like:

data {
  collection [post, post] ...
  archive_title: 'the title',
  archive_description: 'description',
  sidebar: '<markup>',
  etc.
}

I'm loving this plugin, hope it becomes part of wordpress core soon :)

[danielbachhuber]

We should make sure we consistently pass WP_REST_Request and WP_REST_Response to our actions and filters #1238 (comment)

[rachelbaker]

Punted to Beta 4

[BE-Webdesign]

Should we also list the filters and what not on the v2.wp-api.org site?

[danielbachhuber]

Should we also list the filters and what not on the v2.wp-api.org site?

Yes, we could if someone wanted to set that up.

[BE-Webdesign]

Ya I will. What do we need to audit about the filters just to make sure we have a consistent structure and naming to them in the controllers?

[danielbachhuber]

What do we need to audit about the filters just to make sure we have a consistent structure and naming to them in the controllers?

More or less.

[BE-Webdesign]

extras.php

Line	Filter	Function
:81	apply_filters( 'rest_avatar_sizes', array( 24, 48, 96 ) );	rest_get_avatar_sizes()

lib/endpoints/class-wp-rest-attachments-controller.php

Line	Filter	Function
:152	do_action( 'rest_insert_attachment', $attachment, $request, true );	create_item()
:186	do_action( 'rest_insert_attachment', $data, $request, false );	update_item()
:288	apply_filters( 'rest_prepare_attachment', $response, $post, $request );	prepare_item_for_response()

lib/endpoints/class-wp-rest-comments-controller.php

Line	Filter	Function
:164	apply_filters( 'rest_comment_query', $prepared_args, $request );	get_items()
:361	apply_filters( 'rest_pre_insert_comment', $prepared_comment, $request );	create_item()
:390	do_action( 'rest_insert_comment', $comment, $request, true );	create_item()
:460	do_action( 'rest_insert_comment', $comment, $request, false );	update_item()
:506	apply_filters( 'rest_comment_trashable', ( EMPTY_TRASH_DAYS > 0 ), $comment );	delete_item()
:537	do_action( 'rest_delete_comment', $comment, $response, $request );	delete_item()
:596	apply_filters( 'rest_prepare_comment', $response, $comment, $request );	prepare_item_for_response()
:764	apply_filters( 'rest_preprocess_comment', $prepared_comment, $request );	prepare_item_for_database()

lib/endpoints/class-wp-rest-post-statuses-controller.php

Line	Filter	Function
:172	apply_filters( 'rest_prepare_status', $response, $status, $request );	prepare_item_for_response()

lib/endpoints/class-wp-rest-post-types-controller.php

Line	Filter	Function
:136	apply_filters( 'rest_prepare_post_type', $response, $post_type, $request );	prepare_item_for_response()

lib/endpoints/class-wp-rest-posts-controller.php

Line	Filter	Function
:135	apply_filters( "rest_{$this->post_type}_query", $args, $request );	get_items()
:346	do_action( "rest_insert_{$this->post_type}", $post, $request, true );	create_item()
:447	do_action( "rest_insert_{$this->post_type}", $post, $request, false );	update_item()
:500	apply_filters( "rest_{$this->post_type}_trashable", $supports_trash, $post );	delete_item()
:539	do_action( "rest_delete_{$this->post_type}", $post, $response, $request );	delete_item()
:566	apply_filters( "rest_query_var-{$var}", $prepared_args[ $var ] );	prepare_items_query()
:613	apply_filters( 'rest_private_query_vars', $wp->private_query_vars );	get_allowed_query_vars()
:646	apply_filters( 'rest_query_vars', $valid_vars );	get_allowed_query_vars()
:857	apply_filters( "rest_pre_insert_{$this->post_type}", $prepared_post, $request );	prepare_item_for_database()
:1197	apply_filters( "rest_prepare_{$this->post_type}", $response, $post, $request );	prepare_item_for_response()

lib/endpoints/class-wp-rest-revisions-controller.php

Line	Filter	Function
:165	do_action( 'rest_delete_revision', $result, $request );	delete_item()
:228	apply_filters( 'rest_prepare_revision', $response, $post, $request );	prepare_item_for_response()

lib/endpoints/class-wp-rest-taxonomies-controller.php

Line	Filter	Function
:168	apply_filters( 'rest_prepare_taxonomy', $response, $taxonomy, $request );	prepare_item_for_response()

lib/endpoints/class-wp-rest-terms-controller.php

Line	Filter	Function
:137	apply_filters( "rest_{$this->taxonomy}_query", $prepared_args, $request );	get_items()
:372	do_action( "rest_insert_{$this->taxonomy}", $term, $request, true );	create_item()
:442	do_action( "rest_insert_{$this->taxonomy}", $term, $request, false );	update_item()
:502	do_action( "rest_delete_{$this->taxonomy}", $term, $response, $request );	delete_item()
:549	apply_filters( "rest_pre_insert_{$this->taxonomy}", $prepared_term, $request );	prepare_item_for_database()
:592	apply_filters( "rest_prepare_{$this->taxonomy}", $response, $item, $request );	prepare_item_for_response()

lib/endpoints/class-wp-rest-users-controller.php

Line	Filter	Function
:137	apply_filters( 'rest_user_query', $prepared_args, $request );	get_items()
:328	do_action( 'rest_insert_user', $user, $request, true );	create_item()
:411	do_action( 'rest_insert_user', $user, $request, false );	update_item()
:482	do_action( 'rest_delete_user', $user, $response, $request );	delete_item()
:535	apply_filters( 'rest_prepare_user', $response, $user, $request );	prepare_item_for_response()
:615	apply_filters( 'rest_pre_insert_user', $prepared_user, $request );	prepare_item_for_database()

[BE-Webdesign]

I'll get this into a more user friendly format for the docs. This is just here for reviewing the hooks currently in WP API. If there is a more useful format let me know your thoughts and I'll change my script up.

[BE-Webdesign]

In #2396 an interesting discussion was brought up about the use of $creating switch for our insert hooks. wp_insert_post hook in WordPress seems to follow a use of an $updating switch instead. Should we change our hooks to match that pattern?

[BE-Webdesign]

rest_{type}_query Looks consistent across the endpoints.
rest_insert_{type} Looks consistent across the endpoints.
rest_delete_{type} Looks consistent across the endpoints.
rest_prepare_{type} Looks consistent.
rest_pre_insert_{type} Not Consistent.

rest_preprocess_comment used any reason why? Also rest_pre_insert_comment is located in create_item() instead of prepare_item_for_response() The two look like a possible duplicate of each other, unless I am misunderstanding something.

Maybe rest_prepare_status should be changed to rest_prepare_post_status for more clarity but I can see that go either way.

Basic structure looks pretty consistent.

[BE-Webdesign]

Also if both rest_preprocess_comment and rest_pre_insert_comment need to exist, why is rest_pre_insert_comment only in create_item and not update item as well?