WordPress.org

Make WordPress Core

Changeset 38635


Ignore:
Timestamp:
09/20/2016 08:51:18 PM (20 months ago)
Author:
joehoyle
Message:

Options: Build out register_setting like register_meta.

register_setting can now be passed an array arguments to specify meta-data about the setting,
much like using the register_meta API. Of note, it will now accept a show_in_rest arg to
hint the inclusion of the setting in the REST API. get_registered_settings() is available
as a utility to get all registered settings.

Props rmccue, aaroncampbell.
Fixes #37885.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/plugin.php

    r38307 r38635  
    17661766
    17671767/**
    1768  * Register a setting and its sanitization callback
     1768 * Register a setting and its data.
    17691769 *
    17701770 * @since 2.7.0
    17711771 *
    17721772 * @global array $new_whitelist_options
     1773 * @global array $wp_registered_settings
    17731774 *
    17741775 * @param string $option_group A settings group name. Should correspond to a whitelisted option key name.
    17751776 *  Default whitelisted option key names include "general," "discussion," and "reading," among others.
    17761777 * @param string $option_name The name of an option to sanitize and save.
    1777  * @param callable $sanitize_callback A callback function that sanitizes the option's value.
    1778  */
    1779 function register_setting( $option_group, $option_name, $sanitize_callback = '' ) {
    1780     global $new_whitelist_options;
     1778 * @param array  $args {
     1779 *     Data used to describe the setting when registered.
     1780 *
     1781 *     @type string   $type              The type of data associated with this setting.
     1782 *     @type string   $description       A description of the data attached to this setting.
     1783 *     @type callable $sanitize_callback A callback function that sanitizes the option's value.
     1784 *     @type bool     $show_in_rest      Whether data associated with this setting should be included in the REST API.
     1785 * }
     1786 */
     1787function register_setting( $option_group, $option_name, $args = array() ) {
     1788    global $new_whitelist_options, $wp_registered_settings;
     1789
     1790    $defaults = array(
     1791        'type'              => 'string',
     1792        'group'             => $option_group,
     1793        'description'       => '',
     1794        'sanitize_callback' => null,
     1795        'show_in_rest'      => false,
     1796    );
     1797
     1798    // Back-compat: old sanitize callback is added.
     1799    if ( is_callable( $args ) ) {
     1800        $args = array(
     1801            'sanitize_callback' => $args,
     1802        );
     1803    }
     1804
     1805    /**
     1806     * Filters the registration arguments when registering a setting.
     1807     *
     1808     * @since 4.7.0
     1809     *
     1810     * @param array  $args         Array of setting registration arguments.
     1811     * @param array  $defaults     Array of default arguments.
     1812     * @param string $option_group Setting group.
     1813     * @param string $option_name  Setting name.
     1814     */
     1815    $args = apply_filters( 'register_setting_args', $args, $defaults, $option_group, $option_name );
     1816    $args = wp_parse_args( $args, $defaults );
     1817
     1818    if ( ! is_array( $wp_registered_settings ) ) {
     1819        $wp_registered_settings = array();
     1820    }
    17811821
    17821822    if ( 'misc' == $option_group ) {
     
    17911831
    17921832    $new_whitelist_options[ $option_group ][] = $option_name;
    1793     if ( $sanitize_callback != '' )
    1794         add_filter( "sanitize_option_{$option_name}", $sanitize_callback );
    1795 }
    1796 
    1797 /**
    1798  * Unregister a setting
     1833    if ( ! empty( $args['sanitize_callback'] ) ) {
     1834        add_filter( "sanitize_option_{$option_name}", $args['sanitize_callback'] );
     1835    }
     1836
     1837    $wp_registered_settings[ $option_name ] = $args;
     1838}
     1839
     1840/**
     1841 * Unregister a setting.
    17991842 *
    18001843 * @since 2.7.0
     1844 * @since 4.7.0 `$sanitize_callback` was deprecated. The callback from `register_setting()` is now used instead.
    18011845 *
    18021846 * @global array $new_whitelist_options
    18031847 *
    1804  * @param string   $option_group
    1805  * @param string   $option_name
    1806  * @param callable $sanitize_callback
    1807  */
    1808 function unregister_setting( $option_group, $option_name, $sanitize_callback = '' ) {
    1809     global $new_whitelist_options;
     1848 * @param string   $option_group      The settings group name used during registration.
     1849 * @param string   $option_name       The name of the option to unregister.
     1850 * @param callable $deprecated        Deprecated.
     1851 */
     1852function unregister_setting( $option_group, $option_name, $deprecated = '' ) {
     1853    global $new_whitelist_options, $wp_registered_settings;
    18101854
    18111855    if ( 'misc' == $option_group ) {
     
    18201864
    18211865    $pos = array_search( $option_name, (array) $new_whitelist_options[ $option_group ] );
    1822     if ( $pos !== false )
     1866    if ( $pos !== false ) {
    18231867        unset( $new_whitelist_options[ $option_group ][ $pos ] );
    1824     if ( $sanitize_callback != '' )
    1825         remove_filter( "sanitize_option_{$option_name}", $sanitize_callback );
     1868    }
     1869    if ( '' !== $deprecated ) {
     1870        _deprecated_argument( __FUNCTION__, '4.7.0', __( '$sanitize_callback is deprecated. The callback from register_setting() is used instead.' ) );
     1871        remove_filter( "sanitize_option_{$option_name}", $deprecated );
     1872    }
     1873
     1874    if ( isset( $wp_registered_settings[ $option_name ] ) ) {
     1875        // Remove the sanitize callback if one was set during registration.
     1876        if ( ! empty( $wp_registered_settings[ $option_name ]['sanitize_callback'] ) ) {
     1877            remove_filter( "sanitize_option_{$option_name}", $wp_registered_settings[ $option_name ]['sanitize_callback'] );
     1878        }
     1879
     1880        unset( $wp_registered_settings[ $option_name ] );
     1881    }
     1882}
     1883
     1884/**
     1885 * Retrieves an array of registered settings.
     1886 *
     1887 * @since 4.7.0
     1888 *
     1889 * @return array List of registered settings, keyed by option name.
     1890 */
     1891function get_registered_settings() {
     1892    global $wp_registered_settings;
     1893
     1894    if ( ! is_array( $wp_registered_settings ) ) {
     1895        return array();
     1896    }
     1897
     1898    return $wp_registered_settings;
    18261899}
    18271900
Note: See TracChangeset for help on using the changeset viewer.