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

User Contributed Notes

1. Skip to note 11 content

   Bence Szalai 6 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 10You must log in to vote on the helpfulness of this note

   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 12 content

   Farhan Noor 7 years ago

   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

   /**
   * 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 13 content

   Andy Schmidt 7 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

   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.
   }

   • As pointed out by Andy Schmidt the function defined as sanitize_callback will be launched twice, however – at least according to my tests on v4.9.9 – it is only called twice for the first time the setting is submitted and added to the options table in the database. Subsequent updates to the setting execute the sanitize_callback function only once. So unless you are performing something really-really-really heavy operation to sanitize, there’s no need to worry about it, as any workarounds would only save 1 occasion of call to the function per site per plugin installation.

     Bence Szalai 6 years ago
   • A small and very important note remains: When the function is executed the first time, the output will be considered as input to the function the second time

     Mohamed Hamdy 12 months ago
4. Skip to note 14 content

   Corey Salzano 6 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

   If you plan to use your setting in the REST API, use both the rest_api_init and admin_init hooks when calling register_setting() instead of just admin_init. The show_in_rest argument is ineffective when hooked into admin_init alone.
5. Skip to note 15 content

   Codex 9 years ago

   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

   Basic Example

   /**
    * Registers a setting.
    */
   function wpdocs_register_my_setting() {
   	register_setting( 'my_options_group', 'my_option_name', 'intval' ); 
   } 
   add_action( 'admin_init', 'wpdocs_register_my_setting' );
6. Skip to note 16 content

   Ian Dunn 6 years ago

   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

   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',
   		)
   	);
   }

   • Just to add to this, you will also need to use the rest_api_init action if you’re using the JavaScript method for saving settings in wp.api.models (since behind the scenes it also uses the same endpoint)

     Benjamin Intal 2 years ago
7. Skip to note 17 content

   Gerard Reches 1 year ago

   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

   Notice that the sanitization_callback of all the registered settings that share the same $option_group will be executed when saving that option group.

   This sounds obvious, but notice that it will also happen even when the settings that belong to this group are not present in the current page but in a different one.

   For example if we have the following option pages and settings:

   admin.php?page=settings_page_1 containing the optionA form
   admin.php?page=settings_page_2 containing the optionB form

   Where each setting has been registered with their own register_setting() in different files and being output in different pages but the same $option_group string has been used for both of them.

   Saving the page admin.php?page=settings_page_1 will not only trigger the sanitization_callback from optionA, but also the sanitization_callback from optionB.
8. Skip to note 18 content

   Suman 5 years ago

   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

   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' ),
   		)
   	);
   }
9. Skip to note 19 content

   Cloud Stone 4 years ago

   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

   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',
   					),
   				),
   			),
   		),
   	)
   );
10. Skip to note 20 content

    kyajfx 4 years ago

    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

    // 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
    }