register_rest_field() │ WP 4.7.0

Registers a new field on an existing WordPress object type.

Uses: wp_parse_args()
1 time — 0.000001 sec (speed of light) | 50000 times — 0.04 sec (speed of light) | PHP 7.1.11, WP 4.9.8

No Hooks.

Returns

null. Nothing (null).

Usage

register_rest_field( $object_type, $attribute, $args );
$object_type(string|array) (required)
Object(s) the field is being registered to, "post"|"term"|"comment" etc.
$attribute(string) (required)
The attribute name.
$args(array)

An array of arguments used to handle the registered field.

Default: array()

  • get_callback(callable|null)
    Optional. The callback function used to retrieve the field value. The function will be passed the prepared object data.
    Default: 'null', the field will not be returned in the response

  • update_callback(callable|null)
    Optional. The callback function used to set and update the field value. The function will be passed the model object, like WP_Post.
    Default: 'null', the value cannot be set or updated

  • schema(array|null)
    Optional. The schema for this field.
    Default: 'null', no schema entry will be returned

Examples

0

#1 Create a field that displays the name of the author of the post 

add_action( 'rest_api_init', function(){

	register_rest_field( 'post', 'my_awesome_field', array(
		'get_callback' => function( $post, $field_name, $request ){
			return get_the_author_meta( 'display_name', $post['author'] );
		},
		'update_callback' => null,
		'schema' => [
			'description' => __( 'User public name', 'my_domain' ), 
			'type' => 'string'
		],
	) );

} );

Now, the field my_awesome_field can be found in the JSON response of the http://example.com/wp-json/wp/v2/posts route.

0

#2 Get custom posts by custom field. Or update the custom field of a custom post

To make use of sanitize_callback and validate_callback, pass those in arg_options in schema.

add_action( 'rest_api_init', 'slug_register_my_post_types' );

function slug_register_my_post_types() {

	register_rest_field( 'my_post_type', 'my_custom_field',
		[
			'get_callback'    => function( $object, $field_name, $request ) {
				return get_post_meta( $object['id'], $field_name );
			},
			'update_callback' => function( $value, $object, $field_name ) {
				return update_post_meta( $object->ID, $field_name, strip_tags( $value ) );
			},
			'schema'          => [
				'type'        => 'string',
				'arg_options' => [
					'sanitize_callback' => function( $value ) {
						// Make the value safe for storage.
						return sanitize_text_field( $value );
					},
					'validate_callback' => function( $value ) {
						// Valid if it contains exactly 10 English letters.
						return (bool) preg_match( '/\A[a-z]{10}\Z/', $value );
					},
				],
			],
		]
	);
}

With this GET request, you can get a list of posts sorted by the value of the my_custom_field meta-field:

GET https://myexample.com/wp-json/wp/v2/my_post_type?filter[meta_query][0][key]=my_custom_field&filter[meta_query][0][value]=my_find_value

And you can update the value of this meta field with a POST request

POST https://myexample.com/wp-json/wp/v2/my_post_type/{id}

where {id} is the id of the desired post and the query parameters specify: my_custom_field => 'new_value'.

0

#3 Add the featured_image_url field to the post response data

Useful for showing the main image in gutenberg block development when posts are fetched with withSelect() function..

add_action( 'rest_api_init', function () {

	register_rest_field( 'post', 'featured_image_url', array(
		'get_callback' => function ( $post_arr ) {
			$image_data = wp_get_attachment_image_src( $post_arr['featured_media'], 'medium' );

			return $image_data[0];
		},
		'update_callback' => null,
		'schema' => null
	) );
} );
0

#4 Parameters passed to callback functions

For get_callback:

  • $post – (object) Request object, for example WP_Post.
  • $attribute – (string) The field name specified in the second parameter of register_rest_field().
  • $request – (object) All request data in the form of a WP_REST_Request object.
  • $object_type – (string) The object type for which the field was registered. This is usually the value of the first register_rest_field() parameter.

For update_callback:

  • $value – The POST request value for the current field.
  • $post – (object) Request object, for example WP_Post.
  • $attribute – (string) The field name specified in the second parameter of register_rest_field().
  • $request – (object) All request data in the form of a WP_REST_Request object.
  • $object_type – (string) The object type for which the field was registered. This is usually the value of the first register_rest_field() parameter.

Notes

  • Global. Array. $wp_rest_additional_fields Holds registered fields, organized by object type.

Changelog

Since 4.7.0 Introduced.

register_rest_field() code WP 6.8.1

wp-includes/rest-api.php 
function register_rest_field( $object_type, $attribute, $args = array() ) {
	global $wp_rest_additional_fields;

	$defaults = array(
		'get_callback'    => null,
		'update_callback' => null,
		'schema'          => null,
	);

	$args = wp_parse_args( $args, $defaults );

	$object_types = (array) $object_type;

	foreach ( $object_types as $object_type ) {
		$wp_rest_additional_fields[ $object_type ][ $attribute ] = $args;
	}
}

REST API