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

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.     /** 
  20.      * Filters the registration arguments when registering a setting. 
  21.      * 
  22.      * @since 4.7.0 
  23.      * 
  24.      * @param array  $args         Array of setting registration arguments. 
  25.      * @param array  $defaults     Array of default arguments. 
  26.      * @param string $option_group Setting group. 
  27.      * @param string $option_name  Setting name. 
  28.      */ 
  29.     $args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name ); 
  30.     $args = wp_parse_args( $args, $defaults ); 
  31.  
  32.     if ( ! is_array( $wp_registered_settings ) ) { 
  33.         $wp_registered_settings = array(); 
  34.     } 
  35.  
  36.     if ( 'misc' == $option_group ) { 
  37.         _deprecated_argument( __FUNCTION__, '3.0.0', sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ), 'misc' ) ); 
  38.         $option_group = 'general'; 
  39.     } 
  40.  
  41.     if ( 'privacy' == $option_group ) { 
  42.         _deprecated_argument( __FUNCTION__, '3.5.0', sprintf( __( 'The "%s" options group has been removed. Use another settings group.' ), 'privacy' ) ); 
  43.         $option_group = 'reading'; 
  44.     } 
  45.  
  46.     $new_whitelist_options[ $option_group ][] = $option_name; 
  47.     if ( ! empty( $args['sanitize_callback'] ) ) { 
  48.         add_filter( "sanitize_option_{$option_name}", $args['sanitize_callback'] ); 
  49.     } 
  50.     if ( array_key_exists( 'default', $args ) ) { 
  51.         add_filter( "default_option_{$option_name}", 'filter_default_option', 10, 3 ); 
  52.     } 
  53.  
  54.     $wp_registered_settings[ $option_name ] = $args; 
  55. }