WordPress.org

Make WordPress Core

Changeset 38635


Ignore:
Timestamp:
09/20/16 20:51:18 (11 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.