Registering your settings in WordPress 4.7

In WordPress 4.6, register_meta saw improvement enabling developers to specify more information about (post|user|term|comment) metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress., in WordPress 4.7, register_setting has seen similar improvements.

register_setting now accepts an array of arguments in the third parameter, which allows WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. to know more about your setting. This is especially useful in the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/., where WordPress needs to know the type of data your setting is.

The new signature for register_setting is:

@param string $option_group A settings group name.
@param string $option_name The name of an option.
@param array  $args {
    Data used to describe the setting when registered.

    @type string     $type              The type of data associated with this setting. Should be 'number', 'string' or 'boolean' for the REST API.
    @type string     $description       A description of the data attached to this setting.
    @type callable   $sanitize_callback A callback function that sanitizes the option's value.
    @type bool|array $show_in_rest      Whether data associated with this setting should be included in the REST API.
    @type mixed      $default           Default value when calling `get_option()`.
}

In the new $args array, we currently support the types of number, string and boolean in the REST API. Support for objects and arrays will be coming in the future!

The description argument will be used in the REST API also, and potentially other areas of WordPress in the future.

$show_in_rest Can be a boolean or an array of options passed in to the REST API. For example, I can specify a Schema array for my setting when accessed via the REST API so it only has allowed values of private or public:

register_setting( 'general', 'blog_visibility', array(
	'show_in_rest' => array(
		'schema' => array(
			'enum' => array( 'private', 'public' )
		),
	),
	'type' => 'string',
	'default' => 'public',
))

By default, registered settings are NOT included in the REST API, unless you set show_in_rest to either true or an array of options for the REST API.

As you may have noticed from the above, a default argument is also supported. When specified, calling get_option( 'blog_visibility' ) (with no default value passed) will return the registered default. The main advantage is you only have to specify your default once in register_setting rather than every time you make a call to get_option.

#dev-notes