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

Register a setting and its data.

Contents

Description Description

Parameters Parameters

$option_group

(string) (Required) A settings group name. Should correspond to a whitelisted option key name. Default whitelisted option key names include "general," "discussion," and "reading," among others.

$option_name

(string) (Required) The name of an option to sanitize and save.

$args

(array) (Optional) Data used to describe the setting when registered.

  • 'type'
    (string) The type of data associated with this setting. Valid values are 'string', 'boolean', 'integer', and 'number'.
  • 'description'
    (string) A description of the data attached to this setting.
  • 'sanitize_callback'
    (callable) A callback function that sanitizes the option's value.
  • 'show_in_rest'
    (bool) Whether data associated with this setting should be included in the REST API.
  • 'default'
    (mixed) Default value when calling get_option().

Default value: array()

Top ↑

Source Source

File: wp-includes/option.php

2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
function register_setting( $option_group, $option_name, $args = array() ) {
    global $new_whitelist_options, $wp_registered_settings;
 
    $defaults = array(
        'type'              => 'string',
        'group'             => $option_group,
        'description'       => '',
        'sanitize_callback' => null,
        'show_in_rest'      => false,
    );
 
    // Back-compat: old sanitize callback is added.
    if ( is_callable( $args ) ) {
        $args = array(
            'sanitize_callback' => $args,
        );
    }
 
    /**
     * Filters the registration arguments when registering a setting.
     *
     * @since 4.7.0
     *
     * @param array  $args         Array of setting registration arguments.
     * @param array  $defaults     Array of default arguments.
     * @param string $option_group Setting group.
     * @param string $option_name  Setting name.
     */
    $args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name );
    $args = wp_parse_args( $args, $defaults );
 
    if ( ! is_array( $wp_registered_settings ) ) {
        $wp_registered_settings = array();
    }
 
    if ( 'misc' == $option_group ) {
        _deprecated_argument(
            __FUNCTION__,
            '3.0.0',
            /* translators: %s: misc */
            sprintf(
                __( 'The "%s" options group has been removed. Use another settings group.' ),
                'misc'
            )
        );
        $option_group = 'general';
    }
 
    if ( 'privacy' == $option_group ) {
        _deprecated_argument(
            __FUNCTION__,
            '3.5.0',
            /* translators: %s: privacy */
            sprintf(
                __( 'The "%s" options group has been removed. Use another settings group.' ),
                'privacy'
            )
        );
        $option_group = 'reading';
    }
 
    $new_whitelist_options[ $option_group ][] = $option_name;
    if ( ! empty( $args['sanitize_callback'] ) ) {
        add_filter( "sanitize_option_{$option_name}", $args['sanitize_callback'] );
    }
    if ( array_key_exists( 'default', $args ) ) {
        add_filter( "default_option_{$option_name}", 'filter_default_option', 10, 3 );
    }
 
    $wp_registered_settings[ $option_name ] = $args;
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
4.7.0 $args can be passed to set flags on the setting, similar to register_meta().
2.7.0 Introduced.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/option.php: register_setting_args

Filters the registration arguments when registering a setting.
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/functions.php: _deprecated_argument()

Mark a function argument as deprecated and inform when it has been used.
wp-includes/functions.php: wp_parse_args()

Merge user defined arguments into defaults array.
wp-includes/plugin.php: apply_filters()

Call the functions added to a filter hook.
wp-includes/plugin.php: add_filter()

Hook a function or method to a specific filter action.
Show 1 more use Hide more uses

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
    Contributed by Farhan Noor —
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    /**
    * Registers a text field setting for Wordpress 4.7 and higher.
    **/
    function register_my_setting() {
        $args = array(
                'type' => 'string',
                'sanitize_callback' => 'sanitize_text_field',
                'default' => NULL,
                );
        register_setting( 'my_options_group', 'my_option_name', $args );
    }
    add_action( 'admin_init', 'register_my_setting' );
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Andy Schmidt —

    The sanitize callback will be launched twice! Therefore, if sanitizing involves any performance critical or singular tasks, then measures must be taken in the callback to avoid duplicate execution of those portions.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    const   PLUGIN_SLUG =   'MyPlugin';
     
    /*
     *  Setup Plug-In Hooks (Namespaced Example)
     */
    \add_action( 'wp_loaded', __NAMESPACE__.'\on_wp_loaded' );
     
    if ( is_blog_admin() ) {
        \register_activation_hook( __FILE__,  __NAMESPACE__.'\on_activate' );
        \register_deactivation_hook( __FILE__,  __NAMESPACE__.'\on_deactivate' );
         
        \add_action( 'admin_menu', __NAMESPACE__.'\on_admin_menu' );
        \add_action( 'admin_init', __NAMESPACE__.'\on_admin_init' );
        \add_filter( 'plugin_action_links_' . plugin_basename( __FILE__ ), __NAMESPACE__.'\action_links' );
    }
    return;
     
    /*
     *  Add custom options to whitelist, allowing valiated settings to be saved by form.
     */
    function on_admin_init(): void
    {
        \register_setting( PLUGIN_SLUG, PLUGIN_SLUG, [ 'sanitize_callback' => __NAMESPACE__.'\sanitize_settings' ] );
    }
     
    /*
     *  Sanitize the form input.
     */
    function sanitize_settings( $input = NULL ): 
    {
        // Detect multiple sanitizing passes.
        // Accomodates bug: https://core.trac.wordpress.org/ticket/21989
        static $pass_count = 0; $pass_count++;
     
        if ( $pass_count <= 1 ) {
            // Handle any single-time / performane sensitive actions.
     
        }
     
        // Insert regular santizing code here.
    }

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.