register_meta()

You are here:

register_meta( string $object_typestring $meta_keyarray $argsstring|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.


Top ↑

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 to false, 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.

 

$deprecated

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

Default value: null


Top ↑

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 

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;
}


Top ↑

Changelog 

Changelog
VersionDescription
5.5.0The $default argument was added to the arguments array.
5.3.0Valid meta types expanded to include “array” and “object”.
4.9.8The $object_subtype argument was added to the arguments array.
4.6.0Modified 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.0Introduced.
Was this article helpful?
Dislike 0
Views: 3

Cart

Log in

Create an Account
Back to Top