register_meta

Registers a meta key.

Description

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

Parameters (4)

0. $object_type (string)
Type of object this meta is registered to.
1. $meta_key (string)
Meta key to register.
2. $args (array)
Data used to describe the meta key when registered.

Options

  • type (string) => ''

    The type of data associated with this meta key.

  • description (string) => ''

    A description of the data attached to this meta key.

  • single (bool) => null

    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) => ''

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

array(

    /**
     * The type of data associated with this meta key.
     *
     * @type string
     * @default ''
     */
    'type' => '',

    /**
     * A description of the data attached to this meta key.
     *
     * @type string
     * @default ''
     */
    'description' => '',

    /**
     * Whether the meta key has one value per object, or an array of values per object.
     *
     * @type bool
     * @default null
     */
    'single' => null,

    /**
     * A function or method to call when sanitizing `$meta_key` data.
     *
     * @type string
     * @default ''
     */
    'sanitize_callback' => '',

    /**
     * Optional. A function or method to call when performing edit_post_meta, add_post_meta, and
     * delete_post_meta capability checks.
     *
     * @type string
     * @default ''
     * @optional
     */
    'auth_callback' => ''
);        

3. $deprecated — Optional. (null) => null
Deprecated. Use $args instead.

Usage

  1. if ( !function_exists( 'register_meta' ) ) { 
  2. require_once ABSPATH . WPINC . '/meta.php'; 
  3.  
  4. // Type of object this meta is registered to. 
  5. $object_type = ''; 
  6.  
  7. // Meta key to register. 
  8. $meta_key = ''; 
  9.  
  10. // Data used to describe the meta key when registered. 
  11. $args = array( 
  12. 'type' => '', 
  13. 'description' => '', 
  14. 'single' => null, 
  15. 'sanitize_callback' => '', 
  16. 'auth_callback' => '' 
  17. ); 
  18.  
  19. // Deprecated. Use `$args` instead. 
  20. $deprecated = null; 
  21.  
  22. // NOTICE! Understand what this does before running. 
  23. $result = register_meta($object_type, $meta_key, $args, $deprecated); 
  24.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/meta.php  
  1. function register_meta( $object_type, $meta_key, $args, $deprecated = null ) { 
  2. global $wp_meta_keys; 
  3.  
  4. if ( ! is_array( $wp_meta_keys ) ) { 
  5. $wp_meta_keys = array(); 
  6.  
  7. $defaults = array( 
  8. 'type' => 'string',  
  9. 'description' => '',  
  10. 'single' => false,  
  11. 'sanitize_callback' => null,  
  12. 'auth_callback' => null,  
  13. 'show_in_rest' => false,  
  14. ); 
  15.  
  16. // There used to be individual args for sanitize and auth callbacks 
  17. $has_old_sanitize_cb = false; 
  18. $has_old_auth_cb = false; 
  19.  
  20. if ( is_callable( $args ) ) { 
  21. $args = array( 
  22. 'sanitize_callback' => $args,  
  23. ); 
  24.  
  25. $has_old_sanitize_cb = true; 
  26. } else { 
  27. $args = (array) $args; 
  28.  
  29. if ( is_callable( $deprecated ) ) { 
  30. $args['auth_callback'] = $deprecated; 
  31. $has_old_auth_cb = true; 
  32.  
  33. /** 
  34. * Filters the registration arguments when registering meta. 
  35. * @since 4.6.0 
  36. * @param array $args Array of meta registration arguments. 
  37. * @param array $defaults Array of default arguments. 
  38. * @param string $object_type Object type. 
  39. * @param string $meta_key Meta key. 
  40. */ 
  41. $args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key ); 
  42. $args = wp_parse_args( $args, $defaults ); 
  43.  
  44. // If `auth_callback` is not provided, fall back to `is_protected_meta()`. 
  45. if ( empty( $args['auth_callback'] ) ) { 
  46. if ( is_protected_meta( $meta_key, $object_type ) ) { 
  47. $args['auth_callback'] = '__return_false'; 
  48. } else { 
  49. $args['auth_callback'] = '__return_true'; 
  50.  
  51. // Back-compat: old sanitize and auth callbacks are applied to all of an object type. 
  52. if ( is_callable( $args['sanitize_callback'] ) ) { 
  53. add_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'], 10, 3 ); 
  54.  
  55. if ( is_callable( $args['auth_callback'] ) ) { 
  56. add_filter( "auth_{$object_type}_meta_{$meta_key}", $args['auth_callback'], 10, 6 ); 
  57.  
  58. // Global registry only contains meta keys registered with the array of arguments added in 4.6.0. 
  59. if ( ! $has_old_auth_cb && ! $has_old_sanitize_cb ) { 
  60. $wp_meta_keys[ $object_type ][ $meta_key ] = $args; 
  61.  
  62. return true; 
  63.  
  64. return false;