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

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$option_groupstring

A settings group name. Should correspond to an allowed option key name.
Default allowed option key names include 'general', 'discussion', 'media', 'reading', 'writing', and 'options'.

$option_namestring

The name of an option to sanitize and save.

$argsarrayoptional

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

• $typestring

  The type of data associated with this setting. Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.

• $labelstring

  A label of the data attached to this setting.

• $descriptionstring

  A description of the data attached to this setting.

• $sanitize_callbackcallable

  A callback function that sanitizes the option's value.

• $show_in_restbool|array

  Whether data associated with this setting should be included in the REST API. When registering complex settings, this argument may optionally be an array with a 'schema' key.

• $defaultmixeddefault: value when calling get_option()

Performance profile

How much work a call to register_setting() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

56–117

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 117.

Plugin surface

2 hooks

Third-party callbacks on 'register_setting_args', 'register_setting' run inside this call, and their cost is not bounded by anything here.

Called by

7

7 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly

Further down the call graph this can also reach query, option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 18 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost register_setting() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 2

2 hooks fire while register_setting() runs, in this order:

1. 1
   apply_filters( register_setting_args )filterline 3031 (+35 into the body)

   Filters the registration arguments when registering a setting.

2. 2
   do_action( register_setting )actionline 3088 (+92 into the body)

   Fires immediately before the setting is registered but after its filters are in place.

Uses · 7

• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_parse_args()Merges user defined arguments into defaults array.
• _doing_it_wrong()Marks something as being incorrectly called.
• __()Retrieves the translation of $text.
• _deprecated_argument()Marks a function argument as deprecated and inform when it has been used.
• add_filter()Adds a callback function to a filter hook.
• do_action()Calls the callback functions that have been added to an action hook.

Used by · 7

• Featured_Content::register_setting()Registers custom setting on the Settings -> Reading screen.
• _wp_register_default_connector_settings()Registers default connector settings.
• add_option_update_handler()Register a setting and its sanitization callback
• register_block_core_site_icon_setting()Register a core site setting for a site icon
• register_block_core_site_logo_setting()Register a core site setting for a site logo
• register_initial_settings()Registers default settings available in WordPress.
• twentyeleven_theme_options_init()Registers the form setting for our twentyeleven_options array.

Source code

View on Trac ↗View on GitHub ↗

2996function register_setting( $option_group, $option_name, $args = array() ) {2997	global $new_allowed_options, $wp_registered_settings;2998 2999	/*3000	 * In 5.5.0, the `$new_whitelist_options` global variable was renamed to `$new_allowed_options`.3001	 * Please consider writing more inclusive code.3002	 */3003	$GLOBALS['new_whitelist_options'] = &$new_allowed_options;3004 3005	$defaults = array(3006		'type'              => 'string',3007		'group'             => $option_group,3008		'label'             => '',3009		'description'       => '',3010		'sanitize_callback' => null,3011		'show_in_rest'      => false,3012	);3013 3014	// Back-compat: old sanitize callback is added.3015	if ( is_callable( $args ) ) {3016		$args = array(3017			'sanitize_callback' => $args,3018		);3019	}3020 3021	/**3022	 * Filters the registration arguments when registering a setting.3023	 *3024	 * @since 4.7.03025	 *3026	 * @param array  $args         Array of setting registration arguments.3027	 * @param array  $defaults     Array of default arguments.3028	 * @param string $option_group Setting group.3029	 * @param string $option_name  Setting name.3030	 */3031	$args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name );3032 3033	$args = wp_parse_args( $args, $defaults );3034 3035	// Require an item schema when registering settings with an array type.3036	if ( false !== $args['show_in_rest'] && 'array' === $args['type'] && ( ! is_array( $args['show_in_rest'] ) || ! isset( $args['show_in_rest']['schema']['items'] ) ) ) {3037		_doing_it_wrong( __FUNCTION__, __( 'When registering an "array" setting to show in the REST API, you must specify the schema for each array item in "show_in_rest.schema.items".' ), '5.4.0' );3038	}3039 3040	if ( ! is_array( $wp_registered_settings ) ) {3041		$wp_registered_settings = array();3042	}3043 3044	if ( 'misc' === $option_group ) {3045		_deprecated_argument(3046			__FUNCTION__,3047			'3.0.0',3048			sprintf(3049				/* translators: %s: misc */3050				__( 'The "%s" options group has been removed. Use another settings group.' ),3051				'misc'3052			)3053		);3054		$option_group = 'general';3055	}3056 3057	if ( 'privacy' === $option_group ) {3058		_deprecated_argument(3059			__FUNCTION__,3060			'3.5.0',3061			sprintf(3062				/* translators: %s: privacy */3063				__( 'The "%s" options group has been removed. Use another settings group.' ),3064				'privacy'3065			)3066		);3067		$option_group = 'reading';3068	}3069 3070	$new_allowed_options[ $option_group ][] = $option_name;3071 3072	if ( ! empty( $args['sanitize_callback'] ) ) {3073		add_filter( "sanitize_option_{$option_name}", $args['sanitize_callback'] );3074	}3075	if ( array_key_exists( 'default', $args ) ) {

Changelog

Introduced in 2.7.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/option.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.