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

Registers a setting and its data.

Contents

Parameters

$option_group string Required
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_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', 'number', 'array', and 'object'.
  • 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|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.
  • default mixed
    Default value when calling get_option().

Default: array()

Top ↑

Source

File: wp-includes/option.php. View all references 

function register_setting( $option_group, $option_name, $args = array() ) {
	global $new_allowed_options, $wp_registered_settings;

	/*
	 * In 5.5.0, the `$new_whitelist_options` global variable was renamed to `$new_allowed_options`.
	 * Please consider writing more inclusive code.
	 */
	$GLOBALS['new_whitelist_options'] = &$new_allowed_options;

	$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 );

	// Require an item schema when registering settings with an array type.
	if ( false !== $args['show_in_rest'] && 'array' === $args['type'] && ( ! is_array( $args['show_in_rest'] ) || ! isset( $args['show_in_rest']['schema']['items'] ) ) ) {
		_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' );
	}

	if ( ! is_array( $wp_registered_settings ) ) {
		$wp_registered_settings = array();
	}

	if ( 'misc' === $option_group ) {
		_deprecated_argument(
			__FUNCTION__,
			'3.0.0',
			sprintf(
				/* translators: %s: misc */
				__( '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',
			sprintf(
				/* translators: %s: privacy */
				__( 'The "%s" options group has been removed. Use another settings group.' ),
				'privacy'
			)
		);
		$option_group = 'reading';
	}

	$new_allowed_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 );
	}

	/**
	 * Fires immediately before the setting is registered but after its filters are in place.
	 *
	 * @since 5.5.0
	 *
	 * @param string $option_group Setting group.
	 * @param string $option_name  Setting name.
	 * @param array  $args         Array of setting registration arguments.
	 */
	do_action( 'register_setting', $option_group, $option_name, $args );

	$wp_registered_settings[ $option_name ] = $args;
}

View on Trac View on GitHub

Top ↑

Hooks

Top ↑

Top ↑

Uses

Uses
Uses Description
__() wp-includes/l10n.php

Retrieves the translation of $text.
_doing_it_wrong() wp-includes/functions.php

Marks something as being incorrectly called.
_deprecated_argument() wp-includes/functions.php

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

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

Calls the callback functions that have been added to a filter hook.
add_filter() wp-includes/plugin.php

Adds a callback function to a filter hook.
do_action() wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.
Show 5 more uses Hide more uses

Top ↑

Changelog

Changelog
Version Description
5.5.0 $new_whitelist_options was renamed to $new_allowed_options.
Please consider writing more inclusive code.
4.7.0 $args can be passed to set flags on the setting, similar to register_meta().
3.5.0 The privacy option group was deprecated.
3.0.0 The misc option group was deprecated.
2.7.0 Introduced.

Top ↑

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: 8You must log in to vote on the helpfulness of this note
    Contributed by Bence Szalai —

    Some notes about the elements in the $args parameter:

    'type':

    • Only has an effect if 'show_in_rest' is set. So if 'show_in_rest' is false or not part of $args, do not bother with setting a 'type'.
    • Only used by the REST API to define the schema associated with the setting and to implement sanitization over the REST API.
    • Has no effect for the workings of the Admin pages or the way the Setting is handled by the Options API. (I.e.: although probably you shouldn’t, it is possible to submit for example a string value for a setting from the Admin forms that has the 'type' set to "boolean". WP will not complain and will store the value in the options table. It would however cause issues with the REST API, so be careful!)
    • On top of those listed in this page, it also accepts values such as: 'array' and 'object'.

    'description':

    • Only has an effect if 'show_in_rest' is set. So if 'show_in_rest' is false or not part of $args, do not bother with setting a 'description'.
    • Only used by the REST API.

    'default':

    • Affects both the Options API (e.g. get_option()) and the REST API.

    In conclusion: if you do not plan to include your setting in the REST API, it is perfectly enough to only set the 'default' and the 'sanitize_callback' elements in the $args array. Anything else would be ignored anyway.

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note
    Contributed by Farhan Noor — 
    /**
* 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' );
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You 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. 

    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.
}
  6. Skip to note 6 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Ian Dunn —

    If you want the setting to appear in the wp-json/wp/v2/settings endpoint, you’ll need to call register_setting() on the rest_api_init action, in addition to the normal admin_init action.

    add_action( 'admin_init',    'foo_register_settings' );
add_action( 'rest_api_init', 'foo_register_settings' );

function foo_register_settings() {
	register_setting(
		'foo',
		'foo_my_setting',
		array(
			'type'              => 'string',
			'show_in_rest'      => true,
			'sanitize_callback' => 'sanitize_text_field',
		)
	);
}
  7. Skip to note 7 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Suman —

    An example of array settings. if you want to save an array in settings and also show the array setting to appear in the wp-json/wp/v2/settings endpoint, then you have to register show_in_rest schema.

    add_action( 'admin_init',    'wpdocs_foo_register_settings' );
add_action( 'rest_api_init', 'wpdocs_foo_register_settings' );
function wpdocs_foo_register_settings() {
	register_setting( 'general_setting', 'id' );
	register_setting( 'general_setting', 'order' );
	register_setting(
		'general_setting',
		'slider-data',
		array(
			'show_in_rest' => array(
				'name' => 'images_slide',
				'schema' => array(
					'type'  => 'array',
					'items' => array(
						'id'    => 'string',
						'order' => 'string',
					),
				),
			),
			'type' => 'array',
			'sanitize_callback' => array( $this, 'wpdocs_admin_post_save_data' ),
		)
	);
}
  8. Skip to note 8 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Cloud Stone —

    Example for object and array types: 

    register_setting(
	'dp_example_settings_group',
	'dp_example_array_settings',
	array(
		'type'         => 'object',
		'default'      => array(
			'A',
			'B',
			'C',
		),
		'show_in_rest' => array(
			'schema' => array(
				'type'  => 'object',
				'items' => array(
					'type' => 'string',
				),
			),
		),
	)
);

register_setting(
	'dp_example_settings_group',
	'dp_example_object_settings',
	array(
		'type'         => 'object',
		'default'      => array(
			'some_str' => 'A',
			'some_int' => 3,
		),
		'show_in_rest' => array(
			'schema' => array(
				'type'       => 'object',
				'properties' => array(
					'some_str' => array(
						'type' => 'string',
					),
					'some_int' => array(
						'type' => 'integer',
					),
				),
			),
		),
	)
);
  9. Skip to note 9 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 kyajfx — 
    // Registering the field
function wpdocs_add_option_field_to_general_admin_page() {

	register_setting( 'general', 'Field_Name_To_Add' );

	add_settings_field( 
		'field_id-to-add', 
		'Field Name To Display', 
		'wpdocs_setting_callback_function', //Function to Call
		'general', 
		'default', 
		array( 
			'id' => 'field_id-to-add', 
			'option_name' => 'Field_Name_To_Add' 
		)
	);
}

// Adding options to registered field
add_action( 'admin_menu', 'wpdocs_add_option_field_to_general_admin_page' ); // CallBack Function

function wpdocs_setting_callback_function( $val ) {
	$id = $val['id'];
	$option_name = $val['option_name'];
	?>
	<input 
		type="tel" //this can be any HTML input type: date, number, text etc.
		name="<?php echo esc_attr( $option_name ) ?>"
		id="<?php echo esc_attr( $id ) ?>" 
		value="<?php echo esc_attr( get_option( $option_name ) ) ?>" // Displays the value stored in DB
	/> 
	<?php
}

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