Note: The direction of register_meta() has changed since this was published. Please see the most recent developer note explaining these changes.
In 4.6, register_meta() expands to support the registration of meta keys and what to expect from those keys. See #35658 for the discussion around this change.
The behavior of register_meta() is similar to register_post_type() in that the registration of this data is stored in the global scope. This makes an object’s meta data more accessible to parts of core and extending code.
Why make this change
In 4.5 and earlier, WordPress provided no method to explicitly register a meta key’s public state. Instead, register_meta() provided “protected” and “authenticated” meta. This can be used effectively for some things, particularly to determine what meta appears in the Custom Fields metabox when editing a post. It can not be used as a basis for arbitrarily showing meta keys and values to unauthenticated visitors.
What does this change involve
A global variable, $wp_meta_keys, contains all registered meta keys.
The function signature of register_meta() has changed to support 3 arguments, the last being an array. That array should contain data about the meta with these key/values:
sanitize_callback, a callable method to provide sanitization. This is the new version of the current 3rd parameter in register_meta().auth_callback, a callable method to provide authorization. This is the new version of the current 4th parameter in register_meta().object_subtype, a string containing an object subtype slug. If there is no object subtype, meta will not be registered and a WP_Error will be returned instead.type, a string indicating what type of data the meta value will be. This is intentionally not restricted to a specific list of data types, however full names should be used when possible. (e.g. boolean, integer)description, a string containing a basic description of the meta value.single, whether code retrieving meta for this key should expect a single or multiple values when using something like get_post_meta().show_in_rest, whether this should be shown as part of a post’s meta endpoint in the WordPress REST API. Note that this should be treated as experimental until the WordPress REST API provides support for meta.
The register_meta_args filter is available to add support for additional arguments. This need to explicitly whitelist further arguments is to reserve the right for core to add further arguments in the future; should you choose to use this filter, you should be prepared to follow along with further development. Your testing with trunk or betas is greatly appreciated!
By default, only WordPress core object types (post, user, term, comment) can be registered. To add support for custom object types, use the wp_object_types filter. This whitelisting is similar to the above.
Object sub types provide specific registration of meta keys to a type of data.
- A standard WordPress post has an object type of “post” and an object subtype of “post”.
- A custom post type registered with a slug of “my_cpt” has an object type of “post” and an object subtype of “my_cpt”.
- A WordPress user has an object type of “user” and an object subtype of “user”.
- A standard WordPress comment has an object type of “comment” and an object subtype of “comment”.
- A standard WordPress category term has an object type of “term” and an object subtype of “category”.
- A custom taxonomy registered with a slug of “my_tax” has an object type of “term” and an object subtype of “my_tax”.
Meta keys must be explicitly registered for each object type and subtype combination.
Additional helper functions get_registered_metadata(), get_registered_meta_keys(), unregister_meta(), and registered_meta_key_exists() have been added to make the innards of the global data more accessible.
The $wp_meta_keys variable should not be altered directly. It is possible that its structure will change in the future.
Any code currently using register_meta() and expecting pre-4.6 behavior will continue to work as is. Please report any breaks in compatibility that might be found.
Example
Here’s what registering meta looked like in 4.5. This meta key has sanitization and authorization callbacks.
register_meta( 'post', 'my_meta_key', 'sanitize_my_meta_key', 'authorize_my_meta_key' );
The above code will continue to work in 4.6, though will not be considered completely registered. The callbacks will be registered, but the key will not be added to the global registry. A WP_Error object will be returned with this explanation.
Here’s what registering meta looks like in 4.6. This meta key will have sanitization and authorization callbacks, and be registered as public for the WordPress REST API.
$args = array(
'object_subtype' => 'post',
'sanitize_callback' => 'sanitize_my_meta_key',
'auth_callback' => 'authorize_my_meta_key',
'type' => 'string',
'description' => 'My registered meta key',
'single' => true,
'show_in_rest' => true,
);
register_meta( 'post', 'my_meta_key', $args );
If you are currently using register_meta() and would like to maintain support for older versions of WordPress, the best method will be to check for the registration of the sanitization and authorization callbacks after calling register_meta() and then registering them manually if not present. This manual registration is all that register_meta() was previously doing. Continuing from the example above:
// Pre-WordPress 4.6 compatibility
if ( ! has_filter( 'sanitize_post_meta_my_meta_key' ) ) {
add_filter( 'sanitize_post_meta_my_meta_key', 'sanitize_my_meta_key', 10, 4 );
}
if ( ! has_filter( 'auth_post_meta_my_meta_key' ) ) {
add_filter( 'auth_post_meta_my_meta_key', 'authorize_my_meta_key', 10, 6 );
}
What’s next
While the initial work on this is largely driven by the need to move the WordPress REST API forward, its scope is not limited to solving the problem of public access to metadata. By having information about the meta keys used in a code base, it becomes much easier for other pieces of code to make decisions about what can be done with this data.
This data can one day be useful to everything from the Customizer, the editing experience for all object types, the Fields API, and many plugins that rely on metadata. Work will continue on transforming this $wp_meta_keys object and the methods surrounding it to be flexible and explicit. As WordPress core becomes familiar with register_meta() and more confident in the approach, the set of default arguments can and likely will expand to include more data about registered meta keys as required.
Feedback
Please leave any feedback you have on this new iteration of register_meta() in the comments below. Test it out in your plugins and themes to be sure it is working in a backwards compatible way. Try out the new function signature and register meta for objects and their subtypes. This continues to be a work in progress and feedback is important.
#4-6, #dev-notes, #fields-api, #options-meta, #rest-api
