register_setting

Register a setting and its data.

Description

register_setting( (string) $option_group, (string) $option_name, (array) $args = array() ); 

Parameters (3)

0. $option_group (string)
A settings group name. Should correspond to a whitelisted option key name. Default whitelisted option key names include general, "discussion," and reading, among others.
1. $option_name (string)
The name of an option to sanitize and save.
2. $args — Optional. (array) => array()
Data used to describe the setting when registered.

Options

  • type (string) => ''

    The type of data associated with this setting.

  • description (string) => ''

    A description of the data attached to this setting.

  • sanitize_callback (callable) => null

    A callback function that sanitizes the option's value.

  • show_in_rest (bool) => null

    Whether data associated with this setting should be included in the REST API.

array(

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

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

    /**
     * A callback function that sanitizes the option's value.
     *
     * @type callable
     * @default null
     */
    'sanitize_callback' => null,

    /**
     * Whether data associated with this setting should be included in the REST API.
     *
     * @type bool
     * @default null
     */
    'show_in_rest' => null
);        


Usage

  1. if ( !function_exists( 'register_setting' ) ) { 
  2. require_once ABSPATH . WPINC . '/option.php'; 
  3.  
  4. // A settings group name. Should correspond to a whitelisted option key name. 
  5. // Default whitelisted option key names include "general," "discussion," and "reading," among others. 
  6. $option_group = ''; 
  7.  
  8. // The name of an option to sanitize and save. 
  9. $option_name = ''; 
  10.  
  11. // Data used to describe the setting when registered. 
  12. $args = array( 
  13. 'type' => '', 
  14. 'description' => '', 
  15. 'sanitize_callback' => null, 
  16. 'show_in_rest' => null 
  17. ); 
  18.  
  19. // NOTICE! Understand what this does before running. 
  20. $result = register_setting($option_group, $option_name, $args); 
  21.  

Defined (1)

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

/wp-includes/option.php  
  1. function register_setting( $option_group, $option_name, $args = array() ) { 
  2. global $new_whitelist_options, $wp_registered_settings; 
  3.  
  4. $defaults = array( 
  5. 'type' => 'string',  
  6. 'group' => $option_group,  
  7. 'description' => '',  
  8. 'sanitize_callback' => null,  
  9. 'show_in_rest' => false,  
  10. ); 
  11.  
  12. // Back-compat: old sanitize callback is added. 
  13. if ( is_callable( $args ) ) { 
  14. $args = array( 
  15. 'sanitize_callback' => $args,  
  16. ); 
  17.  
  18. /** 
  19. * Filters the registration arguments when registering a setting. 
  20. * @since 4.7.0 
  21. * @param array $args Array of setting registration arguments. 
  22. * @param array $defaults Array of default arguments. 
  23. * @param string $option_group Setting group. 
  24. * @param string $option_name Setting name. 
  25. */ 
  26. $args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name ); 
  27. $args = wp_parse_args( $args, $defaults ); 
  28.  
  29. if ( ! is_array( $wp_registered_settings ) ) { 
  30. $wp_registered_settings = array(); 
  31.  
  32. if ( 'misc' == $option_group ) { 
  33. _deprecated_argument( __FUNCTION__, '3.0.0', sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ), 'misc' ) ); 
  34. $option_group = 'general'; 
  35.  
  36. if ( 'privacy' == $option_group ) { 
  37. _deprecated_argument( __FUNCTION__, '3.5.0', sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ), 'privacy' ) ); 
  38. $option_group = 'reading'; 
  39.  
  40. $new_whitelist_options[ $option_group ][] = $option_name; 
  41. if ( ! empty( $args['sanitize_callback'] ) ) { 
  42. add_filter( "sanitize_option_{$option_name}", $args['sanitize_callback'] ); 
  43. if ( array_key_exists( 'default', $args ) ) { 
  44. add_filter( "default_option_{$option_name}", 'filter_default_option', 10, 3 ); 
  45.  
  46. $wp_registered_settings[ $option_name ] = $args;