WP-API
Audit filters and actions
Let's make sure our controllers have a consistent pattern of filters and actions.
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 :)
We should make sure we consistently pass WP_REST_Request and WP_REST_Response to our actions and filters https://github.com/WP-API/WP-API/issues/1238#issuecomment-102147919
Should we also list the filters and what not on the v2.wp-api.org site?
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.
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?
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.
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() |
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.
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?
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.
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?