register_meta( string $object_type, string $meta_key, array $args, string|array $deprecated = null )
Registers a meta key.
Description Description
It is recommended to register meta keys for a specific combination of object type and object subtype. If passing an object subtype is omitted, the meta key will be registered for the entire object type, however it can be partly overridden in case a more specific meta key of the same name exists for the same object type and a subtype.
If an object type does not support any subtypes, such as users or comments, you should commonly call this function without passing a subtype.
Parameters Parameters
- $object_type
-
(string) (Required) Type of object this meta is registered to.
- $meta_key
-
(string) (Required) Meta key to register.
- $args
-
(array) (Required) Data used to describe the meta key when registered.
- 'object_subtype'
(string) A subtype; e.g. if the object type is "post", the post type. If left empty, the meta key will be registered on the entire object type. Default empty. - 'type'
(string) The type of data associated with this meta key. Valid values are 'string', 'boolean', 'integer', and 'number'. - 'description'
(string) A description of the data attached to this meta key. - 'single'
(bool) Whether the meta key has one value per object, or an array of values per object. - 'sanitize_callback'
(string) A function or method to call when sanitizing$meta_key
data. - 'auth_callback'
(string) Optional. A function or method to call when performing edit_post_meta, add_post_meta, and delete_post_meta capability checks. - 'show_in_rest'
(bool) Whether data associated with this meta key can be considered public.
- 'object_subtype'
- $deprecated
-
(string|array) (Optional) Deprecated. Use
$args
instead.Default value: null
Return Return
(bool) True if the meta key was successfully registered in the global array, false if not. Registering a meta key with distinct sanitize and auth callbacks will fire those callbacks, but will not add to the global registry.
Source Source
File: wp-includes/meta.php
function register_meta( $object_type, $meta_key, $args, $deprecated = null ) { global $wp_meta_keys; if ( ! is_array( $wp_meta_keys ) ) { $wp_meta_keys = array(); } $defaults = array( 'object_subtype' => '', 'type' => 'string', 'description' => '', 'single' => false, 'sanitize_callback' => null, 'auth_callback' => null, 'show_in_rest' => false, ); // There used to be individual args for sanitize and auth callbacks $has_old_sanitize_cb = false; $has_old_auth_cb = false; if ( is_callable( $args ) ) { $args = array( 'sanitize_callback' => $args, ); $has_old_sanitize_cb = true; } else { $args = (array) $args; } if ( is_callable( $deprecated ) ) { $args['auth_callback'] = $deprecated; $has_old_auth_cb = true; } /** * Filters the registration arguments when registering meta. * * @since 4.6.0 * * @param array $args Array of meta registration arguments. * @param array $defaults Array of default arguments. * @param string $object_type Object type. * @param string $meta_key Meta key. */ $args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key ); $args = wp_parse_args( $args, $defaults ); $object_subtype = ! empty( $args['object_subtype'] ) ? $args['object_subtype'] : ''; // If `auth_callback` is not provided, fall back to `is_protected_meta()`. if ( empty( $args['auth_callback'] ) ) { if ( is_protected_meta( $meta_key, $object_type ) ) { $args['auth_callback'] = '__return_false'; } else { $args['auth_callback'] = '__return_true'; } } // Back-compat: old sanitize and auth callbacks are applied to all of an object type. if ( is_callable( $args['sanitize_callback'] ) ) { if ( ! empty( $object_subtype ) ) { add_filter( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $args['sanitize_callback'], 10, 4 ); } else { add_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'], 10, 3 ); } } if ( is_callable( $args['auth_callback'] ) ) { if ( ! empty( $object_subtype ) ) { add_filter( "auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $args['auth_callback'], 10, 6 ); } else { add_filter( "auth_{$object_type}_meta_{$meta_key}", $args['auth_callback'], 10, 6 ); } } // Global registry only contains meta keys registered with the array of arguments added in 4.6.0. if ( ! $has_old_auth_cb && ! $has_old_sanitize_cb ) { unset( $args['object_subtype'] ); $wp_meta_keys[ $object_type ][ $object_subtype ][ $meta_key ] = $args; return true; } return false; }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
4.9.8 | The $object_subtype argument was added to the arguments array. |
4.6.0 | Modified to support an array of data to attach to registered meta keys. Previous arguments for $sanitize_callback and $auth_callback have been folded into this array. |
3.3.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
The values of
$object_type
are not documented but I found.post
for all post types,term
for all taxonomies.There might be other ‘objects’.
As of Wordpress 4.9.8 you can use the
object_subtype
parameter to specify a custom post type. Previously you could only register for all post types. For example to register a meta keymy_meta
for only themy_article
custom post type:Or you can use the new
register_post_meta
function.Basic Example
As of WordPress 4.7, you can use the function as follows. This will be expanded in future versions.
Expand full source codeCollapse full source code
This will return the meta key and meta value in the meta object in the response. For example, an individual post response where id=8 and a meta key `my_postmeta_key` as registered above: