X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/5964d2279dc52bdfe105f9bfa17e04337d47a3fa..a7cd4c052013b423c6301153f68c7fdbaa2a447b:/wp-includes/class-wp-customize-setting.php diff --git a/wp-includes/class-wp-customize-setting.php b/wp-includes/class-wp-customize-setting.php index dd49f79f..d8bf1e23 100644 --- a/wp-includes/class-wp-customize-setting.php +++ b/wp-includes/class-wp-customize-setting.php @@ -2,39 +2,81 @@ /** * Customize Setting Class. * + * Handles saving and sanitizing of settings. + * * @package WordPress * @subpackage Customize * @since 3.4.0 */ class WP_Customize_Setting { + /** + * @access public + * @var WP_Customize_Manager + */ public $manager; + + /** + * @access public + * @var string + */ public $id; - public $type = 'theme_mod'; - public $capability = 'edit_theme_options'; + /** + * @access public + * @var string + */ + public $type = 'theme_mod'; + + /** + * Capability required to edit this setting. + * + * @var string + */ + public $capability = 'edit_theme_options'; + + /** + * Feature a theme is required to support to enable this setting. + * + * @access public + * @var string + */ public $theme_supports = ''; public $default = ''; public $transport = 'refresh'; + /** + * Server-side sanitization callback for the setting's value. + * + * @var callback + */ public $sanitize_callback = ''; public $sanitize_js_callback = ''; protected $id_data = array(); - private $_post_value; // Cached, sanitized $_POST value. + + /** + * Cached and sanitized $_POST value for the setting. + * + * @access private + * @var mixed + */ + private $_post_value; /** * Constructor. * + * Any supplied $args override class property defaults. + * * @since 3.4.0 * * @param WP_Customize_Manager $manager - * @param string $id An specific ID of the setting. Can be a - * theme mod or option name. - * @param array $args Setting arguments. - * @return WP_Customize_Setting + * @param string $id An specific ID of the setting. Can be a + * theme mod or option name. + * @param array $args Setting arguments. + * @return WP_Customize_Setting $setting */ - function __construct( $manager, $id, $args = array() ) { - $keys = array_keys( get_class_vars( __CLASS__ ) ); + public function __construct( $manager, $id, $args = array() ) { + $keys = array_keys( get_object_vars( $this ) ); foreach ( $keys as $key ) { if ( isset( $args[ $key ] ) ) $this->$key = $args[ $key ]; @@ -61,12 +103,18 @@ class WP_Customize_Setting { return $this; } + protected $_original_value; + /** * Handle previewing the setting. * * @since 3.4.0 */ public function preview() { + if ( ! isset( $this->_original_value ) ) { + $this->_original_value = $this->value(); + } + switch( $this->type ) { case 'theme_mod' : add_filter( 'theme_mod_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) ); @@ -80,7 +128,30 @@ class WP_Customize_Setting { } break; default : - do_action( 'customize_preview_' . $this->id ); + + /** + * Fires when the {@see WP_Customize_Setting::preview()} method is called for settings + * not handled as theme_mods or options. + * + * The dynamic portion of the hook name, `$this->id`, refers to the setting ID. + * + * @since 3.4.0 + * + * @param WP_Customize_Setting $this {@see WP_Customize_Setting} instance. + */ + do_action( "customize_preview_{$this->id}", $this ); + + /** + * Fires when the {@see WP_Customize_Setting::preview()} method is called for settings + * not handled as theme_mods or options. + * + * The dynamic portion of the hook name, `$this->type`, refers to the setting type. + * + * @since 4.1.0 + * + * @param WP_Customize_Setting $this {@see WP_Customize_Setting} instance. + */ + do_action( "customize_preview_{$this->type}", $this ); } } @@ -94,15 +165,24 @@ class WP_Customize_Setting { * @return mixed New or old value. */ public function _preview_filter( $original ) { - return $this->multidimensional_replace( $original, $this->id_data[ 'keys' ], $this->post_value() ); + $undefined = new stdClass(); // symbol hack + $post_value = $this->manager->post_value( $this, $undefined ); + if ( $undefined === $post_value ) { + $value = $this->_original_value; + } else { + $value = $post_value; + } + + return $this->multidimensional_replace( $original, $this->id_data['keys'], $value ); } /** - * Set the value of the parameter for a specific theme. + * Check user capabilities and theme supports, and then save + * the value of the setting. * * @since 3.4.0 * - * @return bool False if cap check fails or value isn't set. + * @return false|null False if cap check fails or value isn't set. */ public final function save() { $value = $this->post_value(); @@ -110,13 +190,23 @@ class WP_Customize_Setting { if ( ! $this->check_capabilities() || ! isset( $value ) ) return false; - do_action( 'customize_save_' . $this->id_data[ 'base' ] ); + /** + * Fires when the WP_Customize_Setting::save() method is called. + * + * The dynamic portion of the hook name, `$this->id_data['base']` refers to + * the base slug of the setting name. + * + * @since 3.4.0 + * + * @param WP_Customize_Setting $this {@see WP_Customize_Setting} instance. + */ + do_action( 'customize_save_' . $this->id_data[ 'base' ], $this ); $this->update( $value ); } /** - * Fetches, validates, and sanitizes the $_POST value. + * Fetch and sanitize the $_POST value for the setting. * * @since 3.4.0 * @@ -124,9 +214,11 @@ class WP_Customize_Setting { * @return mixed The default value on failure, otherwise the sanitized value. */ public final function post_value( $default = null ) { + // Check for a cached value if ( isset( $this->_post_value ) ) return $this->_post_value; + // Call the manager for the post value $result = $this->manager->post_value( $this ); if ( isset( $result ) ) @@ -144,12 +236,21 @@ class WP_Customize_Setting { * @return mixed Null if an input isn't valid, otherwise the sanitized value. */ public function sanitize( $value ) { - $value = stripslashes_deep( $value ); + $value = wp_unslash( $value ); + + /** + * Filter a Customize setting value in un-slashed form. + * + * @since 3.4.0 + * + * @param mixed $value Value of the setting. + * @param WP_Customize_Setting $this WP_Customize_Setting instance. + */ return apply_filters( "customize_sanitize_{$this->id}", $value, $this ); } /** - * Set the value of the parameter for a specific theme. + * Save the value of the setting, using the related API. * * @since 3.4.0 * @@ -160,12 +261,24 @@ class WP_Customize_Setting { switch( $this->type ) { case 'theme_mod' : return $this->_update_theme_mod( $value ); - break; + case 'option' : return $this->_update_option( $value ); - break; + default : - return do_action( 'customize_update_' . $this->type, $value ); + + /** + * Fires when the {@see WP_Customize_Setting::update()} method is called for settings + * not handled as theme_mods or options. + * + * The dynamic portion of the hook name, `$this->type`, refers to the type of setting. + * + * @since 3.4.0 + * + * @param mixed $value Value of the setting. + * @param WP_Customize_Setting $this WP_Customize_Setting instance. + */ + return do_action( 'customize_update_' . $this->type, $value, $this ); } } @@ -190,12 +303,12 @@ class WP_Customize_Setting { } /** - * Update the theme mod from the value of the parameter. + * Update the option from the value of the setting. * * @since 3.4.0 * * @param mixed $value The value to update. - * @return mixed The result of saving the value. + * @return bool|null The result of saving the value. */ protected function _update_option( $value ) { // Handle non-array option. @@ -210,13 +323,14 @@ class WP_Customize_Setting { } /** - * Fetch the value of the parameter for a specific theme. + * Fetch the value of the setting. * * @since 3.4.0 * - * @return mixed The requested value. + * @return mixed The value. */ public function value() { + // Get the callback that corresponds to the setting type. switch( $this->type ) { case 'theme_mod' : $function = 'get_theme_mod'; @@ -225,6 +339,20 @@ class WP_Customize_Setting { $function = 'get_option'; break; default : + + /** + * Filter a Customize setting value not handled as a theme_mod or option. + * + * The dynamic portion of the hook name, `$this->id_date['base']`, refers to + * the base slug of the setting name. + * + * For settings handled as theme_mods or options, see those corresponding + * functions for available hooks. + * + * @since 3.4.0 + * + * @param mixed $default The setting default value. Default empty. + */ return apply_filters( 'customize_value_' . $this->id_data[ 'base' ], $this->default ); } @@ -238,13 +366,24 @@ class WP_Customize_Setting { } /** - * Escape the parameter's value for use in JavaScript. + * Sanitize the setting's value for use in JavaScript. * * @since 3.4.0 * * @return mixed The requested escaped value. */ public function js_value() { + + /** + * Filter a Customize setting value for use in JavaScript. + * + * The dynamic portion of the hook name, `$this->id`, refers to the setting ID. + * + * @since 3.4.0 + * + * @param mixed $value The setting value. + * @param WP_Customize_Setting $this {@see WP_Customize_Setting} instance. + */ $value = apply_filters( "customize_sanitize_js_{$this->id}", $this->value(), $this ); if ( is_string( $value ) ) @@ -254,7 +393,7 @@ class WP_Customize_Setting { } /** - * Check if the theme supports the setting and check user capabilities. + * Validate user capabilities whether the theme supports the setting. * * @since 3.4.0 * @@ -300,8 +439,15 @@ class WP_Customize_Setting { $node = &$node[ $key ]; } - if ( $create && ! isset( $node[ $last ] ) ) - $node[ $last ] = array(); + if ( $create ) { + if ( ! is_array( $node ) ) { + // account for an array overriding a string or object value + $node = array(); + } + if ( ! isset( $node[ $last ] ) ) { + $node[ $last ] = array(); + } + } if ( ! isset( $node[ $last ] ) ) return; @@ -344,7 +490,7 @@ class WP_Customize_Setting { * * @param $root * @param $keys - * @param $default A default value which is used as a fallback. Default is null. + * @param mixed $default A default value which is used as a fallback. Default is null. * @return mixed The requested value or the default value. */ final protected function multidimensional_get( $root, $keys, $default = null ) { @@ -420,6 +566,8 @@ final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting { } /** + * Class WP_Customize_Background_Image_Setting + * * @package WordPress * @subpackage Customize * @since 3.4.0 @@ -429,7 +577,6 @@ final class WP_Customize_Background_Image_Setting extends WP_Customize_Setting { /** * @since 3.4.0 - * @uses remove_theme_mod() * * @param $value */