register_meta( string $object_type, string $meta_key, array $args, string|array $deprecated = null )
Registers a meta key.
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
- $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. - ‘default’
(mixed) 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 tofalse
, the default value given here will be wrapped in an array. - ‘sanitize_callback’
(callable) A function or method to call when sanitizing$meta_key
data. - ‘auth_callback’
(callable) 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.
- ‘object_subtype’
- $deprecated
-
(string|array) (Optional) Deprecated. Use
$args
instead.Default value: null
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
File: wp-includes/meta.php
1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 |
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' => '' , 'default' => '' , '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 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. */ $args = apply_filters( 'register_meta_args' , $args , $defaults , $object_type , $meta_key ); unset( $defaults [ 'default' ] ); $args = wp_parse_args( $args , $defaults ); // Require an item schema when registering array meta. if ( false !== $args [ 'show_in_rest' ] && 'array' === $args [ 'type' ] ) { if ( ! is_array ( $args [ 'show_in_rest' ] ) || ! isset( $args [ 'show_in_rest' ][ 'schema' ][ 'items' ] ) ) { _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' ); return false; } } $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 ); } } if ( array_key_exists ( 'default' , $args ) ) { $schema = $args ; if ( is_array ( $args [ 'show_in_rest' ] ) && isset( $args [ 'show_in_rest' ][ 'schema' ] ) ) { $schema = array_merge ( $schema , $args [ 'show_in_rest' ][ 'schema' ] ); } $check = rest_validate_value_from_schema( $args [ 'default' ], $schema ); if ( is_wp_error( $check ) ) { _doing_it_wrong( __FUNCTION__ , __( 'When registering a default meta value the data must match the type provided.' ), '5.5.0' ); return false; } if ( ! has_filter( "default_{$object_type}_metadata" , 'filter_default_metadata' ) ) { add_filter( "default_{$object_type}_metadata" , 'filter_default_metadata' , 10, 5 ); } } // 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 View on Trac
Changelog
Version | Description |
---|---|
5.5.0 | The $default argument was added to the arguments array. |
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. |