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

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$object_typestring

Type of object metadata is for. Accepts 'blog', 'post', 'comment', 'term', 'user', or any other object type with an associated meta table.

$meta_keystring

Meta key to register.

$argsarray

Data used to describe the meta key when registered.

• $object_subtypestringdefault: empty

  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.

• $typestring

  The type of data associated with this meta key. Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.

• $labelstring

  A human-readable label of the data attached to this meta key.

• $descriptionstring

  A description of the data attached to this meta key.

• $singlebool

  Whether the meta key has one value per object, or an array of values per object.

• $defaultmixed

  The default value returned from get_metadata() if no value has been set yet. When using a non-single meta key, the default value is for the first entry. In other words, when calling get_metadata() with $single set to false, the default value given here will be wrapped in an array.

• $sanitize_callbackcallable

  A function or method to call when sanitizing $meta_key data.

• $auth_callbackcallable

  Optional. A function or method to call when performing edit_post_meta, add_post_meta, and delete_post_meta capability checks.

• $show_in_restbool|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.

• $revisions_enabledbool

  Whether to enable revisions support for this meta_key. Can only be used when the object type is 'post'.

$deprecatedstring|arrayoptional

Deprecated. Use $args instead.Default: null

Return value

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.

Performance profile

How much work a call to register_meta() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

54–159

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 241.

Plugin surface

1 hook

Third-party callbacks on 'register_meta_args' run inside this call, and their cost is not bounded by anything here.

Called by

4

4 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly

Further down the call graph this can also reach option, cache, serialize, query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 114 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost register_meta() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 1

One hook fires while register_meta() runs, in this order:

1. 1
   apply_filters( register_meta_args )filterline 1485 (+50 into the body)

   Filters the registration arguments when registering meta.

Uses · 10

• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_parse_args()Merges user defined arguments into defaults array.
• _doing_it_wrong()Marks something as being incorrectly called.
• __()Retrieves the translation of $text.
• post_type_supports()Checks a post type's support for a given feature.
• is_protected_meta()Determines whether a meta key is considered protected.
• add_filter()Adds a callback function to a filter hook.
• rest_validate_value_from_schema()Validate a value based on a schema.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• has_filter()Checks if any filter has been registered for a hook.

Used by · 4

• register_post_meta()Registers a meta key for posts.
• register_term_meta()Registers a meta key for terms.
• wp_create_initial_comment_meta()Register initial note status meta.
• wp_register_persisted_preferences_meta()Registers the user meta property for persisted preferences.

Source code

View on Trac ↗View on GitHub ↗

1435function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {1436	global $wp_meta_keys;1437 1438	if ( ! is_array( $wp_meta_keys ) ) {1439		$wp_meta_keys = array();1440	}1441 1442	$defaults = array(1443		'object_subtype'    => '',1444		'type'              => 'string',1445		'label'             => '',1446		'description'       => '',1447		'default'           => '',1448		'single'            => false,1449		'sanitize_callback' => null,1450		'auth_callback'     => null,1451		'show_in_rest'      => false,1452		'revisions_enabled' => false,1453	);1454 1455	// There used to be individual args for sanitize and auth callbacks.1456	$has_old_sanitize_cb = false;1457	$has_old_auth_cb     = false;1458 1459	if ( is_callable( $args ) ) {1460		$args = array(1461			'sanitize_callback' => $args,1462		);1463 1464		$has_old_sanitize_cb = true;1465	} else {1466		$args = (array) $args;1467	}1468 1469	if ( is_callable( $deprecated ) ) {1470		$args['auth_callback'] = $deprecated;1471		$has_old_auth_cb       = true;1472	}1473 1474	/**1475	 * Filters the registration arguments when registering meta.1476	 *1477	 * @since 4.6.01478	 *1479	 * @param array  $args        Array of meta registration arguments.1480	 * @param array  $defaults    Array of default arguments.1481	 * @param string $object_type Type of object metadata is for. Accepts 'blog', 'post', 'comment', 'term',1482	 *                            'user', or any other object type with an associated meta table.1483	 * @param string $meta_key    Meta key.1484	 */1485	$args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key );1486	unset( $defaults['default'] );1487	$args = wp_parse_args( $args, $defaults );1488 1489	// Require an item schema when registering array meta.1490	if ( false !== $args['show_in_rest'] && 'array' === $args['type'] ) {1491		if ( ! is_array( $args['show_in_rest'] ) || ! isset( $args['show_in_rest']['schema']['items'] ) ) {1492			_doing_it_wrong( __FUNCTION__, __( 'When registering an "array" meta type to show in the REST API, you must specify the schema for each array item in "show_in_rest.schema.items".' ), '5.3.0' );1493 1494			return false;1495		}1496	}1497 1498	$object_subtype = ! empty( $args['object_subtype'] ) ? $args['object_subtype'] : '';1499	if ( $args['revisions_enabled'] ) {1500		if ( 'post' !== $object_type ) {1501			_doing_it_wrong( __FUNCTION__, __( 'Meta keys cannot enable revisions support unless the object type supports revisions.' ), '6.4.0' );1502 1503			return false;1504		} elseif ( ! empty( $object_subtype ) && ! post_type_supports( $object_subtype, 'revisions' ) ) {1505			_doing_it_wrong( __FUNCTION__, __( 'Meta keys cannot enable revisions support unless the object subtype supports revisions.' ), '6.4.0' );1506 1507			return false;1508		}1509	}1510 1511	// If `auth_callback` is not provided, fall back to `is_protected_meta()`.1512	if ( empty( $args['auth_callback'] ) ) {1513		if ( is_protected_meta( $meta_key, $object_type ) ) {1514			$args['auth_callback'] = '__return_false';

Changelog

Introduced in 3.3.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/meta.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.