register_meta

Advertisement

Summery Summery

Registers a meta key.

Syntax Syntax

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

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 metadata is for. Accepts 'post', 'comment', 'term', 'user', or any other object type with an associated meta table.

$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', 'number', 'array', and 'object'.
  • '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|array) Whether data associated with this meta key can be considered public and should be accessible via the REST API. A custom post type must also declare support for custom fields for registered meta to be accessible via REST. When registering complex meta values this argument may optionally be an array with 'schema' or 'prepare_callback' keys instead of a boolean.

$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

 * @param string $meta_type Optional. Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
 *                          or any other object type with an associated meta table. Default empty.
 * @return bool Whether the meta key is considered protected.
 */
function is_protected_meta( $meta_key, $meta_type = '' ) {
	$protected = ( '_' === $meta_key[0] );

	/**
	 * Filters whether a meta key is considered protected.
	 *
	 * @since 3.2.0
	 *
	 * @param bool   $protected Whether the key is considered protected.
	 * @param string $meta_key  Metadata key.
	 * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
	 *                          or any other object type with an associated meta table.
	 */
	return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
}

/**
 * Sanitizes meta value.
 *
 * @since 3.1.3
 * @since 4.9.8 The `$object_subtype` parameter was added.
 *
 * @param string $meta_key       Metadata key.
 * @param mixed  $meta_value     Metadata value to sanitize.
 * @param string $object_type    Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
 *                               or any other object type with an associated meta table.
 * @param string $object_subtype Optional. The subtype of the object type.
 * @return mixed Sanitized $meta_value.
 */
function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype = '' ) {
	if ( ! empty( $object_subtype ) && has_filter( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}" ) ) {

		/**
		 * Filters the sanitization of a specific meta key of a specific meta type and subtype.
		 *
		 * The dynamic portions of the hook name, `$object_type`, `$meta_key`,
		 * and `$object_subtype`, refer to the metadata object type (comment, post, term, or user),
		 * the meta key value, and the object subtype respectively.
		 *
		 * @since 4.9.8
		 *
		 * @param mixed  $meta_value     Metadata value to sanitize.
		 * @param string $meta_key       Metadata key.
		 * @param string $object_type    Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
		 *                               or any other object type with an associated meta table.
		 * @param string $object_subtype Object subtype.
		 */
		return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $meta_value, $meta_key, $object_type, $object_subtype );
	}

	/**
	 * Filters the sanitization of a specific meta key of a specific meta type.
	 *
	 * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
	 * refer to the metadata object type (comment, post, term, or user) and the meta
	 * key value, respectively.
	 *
	 * @since 3.3.0
	 *
	 * @param mixed  $meta_value  Metadata value to sanitize.
	 * @param string $meta_key    Metadata key.
	 * @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
	 *                            or any other object type with an associated meta table.
	 */
	return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}", $meta_value, $meta_key, $object_type );
}

/**
 * Registers a meta key.
 *
 * 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.
 *
 * @since 3.3.0
 * @since 4.6.0 {@link https://core.trac.wordpress.org/ticket/35658 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.
 * @since 4.9.8 The `$object_subtype` argument was added to the arguments array.
 * @since 5.3.0 Valid meta types expanded to include "array" and "object".
 * @since 5.5.0 The `$default` argument was added to the arguments array.
 *
 * @param string       $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
 *                                  or any other object type with an associated meta table.
 * @param string       $meta_key    Meta key to register.
 * @param array        $args {
 *     Data used to describe the meta key when registered.
 *
 *     @type string     $object_subtype    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     $type              The type of data associated with this meta key.

Advertisement

Changelog Changelog

Changelog
Version Description
5.3.0 Valid meta types expanded to include "array" and "object".
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.

Advertisement

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.