register_meta( string $object_type, string $meta_key, array $args, string|array $deprecated = null )

Registers a meta key.


Description Description


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.

  • '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.

$deprecated

(string|array) (Optional) Deprecated. Use $args instead.

Default value: null


Top ↑

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.


Top ↑

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(
		'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 );

	// 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'] ) ) {
		add_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'], 10, 3 );
	}

	if ( is_callable( $args['auth_callback'] ) ) {
		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 ) {
		$wp_meta_keys[ $object_type ][ $meta_key ] = $args;

		return true;
	}

	return false;
}

Top ↑

Changelog Changelog

Changelog
Version Description
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.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note content
    Contributed by tharsheblows

    As of WordPress 4.7, you can use the function as follows. This will be expanded in future versions.

    $object_type = 'post'; // The object type. 
    	// For custom post types, this is 'post', for custom comment types, this is 'comment'.
    
    $args1 = array(
        'type'		=> 'string', // Validate and sanitize the meta value as a string.
    		// Default: 'string'.  
        	// In 4.7 one of 'string', 'boolean', 'integer', 'number' must be used as 'type'. 
        'description'    => 'A meta key associated with a string meta value.', // Shown in the schema for the meta key.
        'single'        => true, // Return a single value of the type. Default: false.
        'show_in_rest'    => true, // Show in the WP REST API response. Default: false.
    );
    
    register_meta( $object_type, 'my_postmeta_key', $args1 );
    
    
    $args2 = array(
        'type'             => 'string', // Validate and sanitize the meta value as a string.
        'description'    => 'A meta key associated with a string meta value.', // Shown in the schema for the meta key.
        'single'        => false, // Return an array with the type used as the items type. Default: false.
        'show_in_rest'    => true, // Show in the WP REST API response. Default: false.
    );
    
    register_meta( 'user', 'my_usermeta_key', $args2 );

    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:

    {
      "id": 8, // the post id
     	...
      "meta": {
        "my_postmeta_key": "the meta value"
      },
    	...
    }
  2. Skip to note content
    Contributed by Ian Dunn

    As of WordPress 4.7, there’s no way to register a meta field for a specific post type. Registering a field registers it for all post types, and registering it with show_in_rest => true exposes it in all REST API endpoints.

    That may seem harmless if you don’t stop to think about, but doing it could lead to unintentional privacy leaks. For example, an email_address field might be perfectly safe to expose in one endpoint (e.g., something that’s already public like support@example.org), but exposing that same field on a different post type could be leaking someone’s private information.

    So, make sure you consider that before registering a field for all endpoints.

    There’s a proposal to add support for specific post types in #38323.

You must log in before being able to contribute a note or feedback.