wp-includes/class-wp-customize-setting.php

   1 <?php
   2 /**
   3  * Customize Setting Class.
   4  *
   5  * Handles saving and sanitizing of settings.
   6  *
   7  * @package WordPress
   8  * @subpackage Customize
   9  * @since 3.4.0
  10  */
  11 class WP_Customize_Setting {
  12         /**
  13          * @access public
  14          * @var WP_Customize_Manager
  15          */
  16         public $manager;
  17
  18         /**
  19          * @access public
  20          * @var string
  21          */
  22         public $id;
  23
  24         /**
  25          * @access public
  26          * @var string
  27          */
  28         public $type = 'theme_mod';
  29
  30         /**
  31          * Capability required to edit this setting.
  32          *
  33          * @var string
  34          */
  35         public $capability = 'edit_theme_options';
  36
  37         /**
  38          * Feature a theme is required to support to enable this setting.
  39          *
  40          * @access public
  41          * @var string
  42          */
  43         public $theme_supports  = '';
  44         public $default         = '';
  45         public $transport       = 'refresh';
  46
  47         /**
  48          * Server-side sanitization callback for the setting's value.
  49          *
  50          * @var callback
  51          */
  52         public $sanitize_callback    = '';
  53         public $sanitize_js_callback = '';
  54
  55         protected $id_data = array();
  56
  57         /**
  58          * Cached and sanitized $_POST value for the setting.
  59          *
  60          * @access private
  61          * @var mixed
  62          */
  63         private $_post_value;
  64
  65         /**
  66          * Constructor.
  67          *
  68          * Any supplied $args override class property defaults.
  69          *
  70          * @since 3.4.0
  71          *
  72          * @param WP_Customize_Manager $manager
  73          * @param string               $id      An specific ID of the setting. Can be a
  74          *                                      theme mod or option name.
  75          * @param array                $args    Setting arguments.
  76          * @return WP_Customize_Setting $setting
  77          */
  78         public function __construct( $manager, $id, $args = array() ) {
  79                 $keys = array_keys( get_object_vars( $this ) );
  80                 foreach ( $keys as $key ) {
  81                         if ( isset( $args[ $key ] ) )
  82                                 $this->$key = $args[ $key ];
  83                 }
  84
  85                 $this->manager = $manager;
  86                 $this->id = $id;
  87
  88                 // Parse the ID for array keys.
  89                 $this->id_data[ 'keys' ] = preg_split( '/\[/', str_replace( ']', '', $this->id ) );
  90                 $this->id_data[ 'base' ] = array_shift( $this->id_data[ 'keys' ] );
  91
  92                 // Rebuild the ID.
  93                 $this->id = $this->id_data[ 'base' ];
  94                 if ( ! empty( $this->id_data[ 'keys' ] ) )
  95                         $this->id .= '[' . implode( '][', $this->id_data[ 'keys' ] ) . ']';
  96
  97                 if ( $this->sanitize_callback )
  98                         add_filter( "customize_sanitize_{$this->id}", $this->sanitize_callback, 10, 2 );
  99
 100                 if ( $this->sanitize_js_callback )
 101                         add_filter( "customize_sanitize_js_{$this->id}", $this->sanitize_js_callback, 10, 2 );
 102
 103                 return $this;
 104         }
 105
 106         /**
 107          * Handle previewing the setting.
 108          *
 109          * @since 3.4.0
 110          */
 111         public function preview() {
 112                 switch( $this->type ) {
 113                         case 'theme_mod' :
 114                                 add_filter( 'theme_mod_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) );
 115                                 break;
 116                         case 'option' :
 117                                 if ( empty( $this->id_data[ 'keys' ] ) )
 118                                         add_filter( 'pre_option_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) );
 119                                 else {
 120                                         add_filter( 'option_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) );
 121                                         add_filter( 'default_option_' . $this->id_data[ 'base' ], array( $this, '_preview_filter' ) );
 122                                 }
 123                                 break;
 124                         default :
 125
 126                                 /**
 127                                  * Fires when the {@see WP_Customize_Setting::preview()} method is called for settings
 128                                  * not handled as theme_mods or options.
 129                                  *
 130                                  * The dynamic portion of the hook name, `$this->id`, refers to the setting ID.
 131                                  *
 132                                  * @since 3.4.0
 133                                  *
 134                                  * @param WP_Customize_Setting $this {@see WP_Customize_Setting} instance.
 135                                  */
 136                                 do_action( "customize_preview_{$this->id}", $this );
 137
 138                                 /**
 139                                  * Fires when the {@see WP_Customize_Setting::preview()} method is called for settings
 140                                  * not handled as theme_mods or options.
 141                                  *
 142                                  * The dynamic portion of the hook name, `$this->type`, refers to the setting type.
 143                                  *
 144                                  * @since 4.1.0
 145                                  *
 146                                  * @param WP_Customize_Setting $this {@see WP_Customize_Setting} instance.
 147                                  */
 148                                 do_action( "customize_preview_{$this->type}", $this );
 149                 }
 150         }
 151
 152         /**
 153          * Callback function to filter the theme mods and options.
 154          *
 155          * @since 3.4.0
 156          * @uses WP_Customize_Setting::multidimensional_replace()
 157          *
 158          * @param mixed $original Old value.
 159          * @return mixed New or old value.
 160          */
 161         public function _preview_filter( $original ) {
 162                 return $this->multidimensional_replace( $original, $this->id_data[ 'keys' ], $this->post_value() );
 163         }
 164
 165         /**
 166          * Check user capabilities and theme supports, and then save
 167          * the value of the setting.
 168          *
 169          * @since 3.4.0
 170          *
 171          * @return false|null False if cap check fails or value isn't set.
 172          */
 173         public final function save() {
 174                 $value = $this->post_value();
 175
 176                 if ( ! $this->check_capabilities() || ! isset( $value ) )
 177                         return false;
 178
 179                 /**
 180                  * Fires when the WP_Customize_Setting::save() method is called.
 181                  *
 182                  * The dynamic portion of the hook name, `$this->id_data['base']` refers to
 183                  * the base slug of the setting name.
 184                  *
 185                  * @since 3.4.0
 186                  *
 187                  * @param WP_Customize_Setting $this {@see WP_Customize_Setting} instance.
 188                  */
 189                 do_action( 'customize_save_' . $this->id_data[ 'base' ], $this );
 190
 191                 $this->update( $value );
 192         }
 193
 194         /**
 195          * Fetch and sanitize the $_POST value for the setting.
 196          *
 197          * @since 3.4.0
 198          *
 199          * @param mixed $default A default value which is used as a fallback. Default is null.
 200          * @return mixed The default value on failure, otherwise the sanitized value.
 201          */
 202         public final function post_value( $default = null ) {
 203                 // Check for a cached value
 204                 if ( isset( $this->_post_value ) )
 205                         return $this->_post_value;
 206
 207                 // Call the manager for the post value
 208                 $result = $this->manager->post_value( $this );
 209
 210                 if ( isset( $result ) )
 211                         return $this->_post_value = $result;
 212                 else
 213                         return $default;
 214         }
 215
 216         /**
 217          * Sanitize an input.
 218          *
 219          * @since 3.4.0
 220          *
 221          * @param mixed $value The value to sanitize.
 222          * @return mixed Null if an input isn't valid, otherwise the sanitized value.
 223          */
 224         public function sanitize( $value ) {
 225                 $value = wp_unslash( $value );
 226
 227                 /**
 228                  * Filter a Customize setting value in un-slashed form.
 229                  *
 230                  * @since 3.4.0
 231                  *
 232                  * @param mixed                $value Value of the setting.
 233                  * @param WP_Customize_Setting $this  WP_Customize_Setting instance.
 234                  */
 235                 return apply_filters( "customize_sanitize_{$this->id}", $value, $this );
 236         }
 237
 238         /**
 239          * Save the value of the setting, using the related API.
 240          *
 241          * @since 3.4.0
 242          *
 243          * @param mixed $value The value to update.
 244          * @return mixed The result of saving the value.
 245          */
 246         protected function update( $value ) {
 247                 switch( $this->type ) {
 248                         case 'theme_mod' :
 249                                 return $this->_update_theme_mod( $value );
 250
 251                         case 'option' :
 252                                 return $this->_update_option( $value );
 253
 254                         default :
 255
 256                                 /**
 257                                  * Fires when the {@see WP_Customize_Setting::update()} method is called for settings
 258                                  * not handled as theme_mods or options.
 259                                  *
 260                                  * The dynamic portion of the hook name, `$this->type`, refers to the type of setting.
 261                                  *
 262                                  * @since 3.4.0
 263                                  *
 264                                  * @param mixed                $value Value of the setting.
 265                                  * @param WP_Customize_Setting $this  WP_Customize_Setting instance.
 266                                  */
 267                                 return do_action( 'customize_update_' . $this->type, $value, $this );
 268                 }
 269         }
 270
 271         /**
 272          * Update the theme mod from the value of the parameter.
 273          *
 274          * @since 3.4.0
 275          *
 276          * @param mixed $value The value to update.
 277          * @return mixed The result of saving the value.
 278          */
 279         protected function _update_theme_mod( $value ) {
 280                 // Handle non-array theme mod.
 281                 if ( empty( $this->id_data[ 'keys' ] ) )
 282                         return set_theme_mod( $this->id_data[ 'base' ], $value );
 283
 284                 // Handle array-based theme mod.
 285                 $mods = get_theme_mod( $this->id_data[ 'base' ] );
 286                 $mods = $this->multidimensional_replace( $mods, $this->id_data[ 'keys' ], $value );
 287                 if ( isset( $mods ) )
 288                         return set_theme_mod( $this->id_data[ 'base' ], $mods );
 289         }
 290
 291         /**
 292          * Update the option from the value of the setting.
 293          *
 294          * @since 3.4.0
 295          *
 296          * @param mixed $value The value to update.
 297          * @return bool|null The result of saving the value.
 298          */
 299         protected function _update_option( $value ) {
 300                 // Handle non-array option.
 301                 if ( empty( $this->id_data[ 'keys' ] ) )
 302                         return update_option( $this->id_data[ 'base' ], $value );
 303
 304                 // Handle array-based options.
 305                 $options = get_option( $this->id_data[ 'base' ] );
 306                 $options = $this->multidimensional_replace( $options, $this->id_data[ 'keys' ], $value );
 307                 if ( isset( $options ) )
 308                         return update_option( $this->id_data[ 'base' ], $options );
 309         }
 310
 311         /**
 312          * Fetch the value of the setting.
 313          *
 314          * @since 3.4.0
 315          *
 316          * @return mixed The value.
 317          */
 318         public function value() {
 319                 // Get the callback that corresponds to the setting type.
 320                 switch( $this->type ) {
 321                         case 'theme_mod' :
 322                                 $function = 'get_theme_mod';
 323                                 break;
 324                         case 'option' :
 325                                 $function = 'get_option';
 326                                 break;
 327                         default :
 328
 329                                 /**
 330                                  * Filter a Customize setting value not handled as a theme_mod or option.
 331                                  *
 332                                  * The dynamic portion of the hook name, `$this->id_date['base']`, refers to
 333                                  * the base slug of the setting name.
 334                                  *
 335                                  * For settings handled as theme_mods or options, see those corresponding
 336                                  * functions for available hooks.
 337                                  *
 338                                  * @since 3.4.0
 339                                  *
 340                                  * @param mixed $default The setting default value. Default empty.
 341                                  */
 342                                 return apply_filters( 'customize_value_' . $this->id_data[ 'base' ], $this->default );
 343                 }
 344
 345                 // Handle non-array value
 346                 if ( empty( $this->id_data[ 'keys' ] ) )
 347                         return $function( $this->id_data[ 'base' ], $this->default );
 348
 349                 // Handle array-based value
 350                 $values = $function( $this->id_data[ 'base' ] );
 351                 return $this->multidimensional_get( $values, $this->id_data[ 'keys' ], $this->default );
 352         }
 353
 354         /**
 355          * Sanitize the setting's value for use in JavaScript.
 356          *
 357          * @since 3.4.0
 358          *
 359          * @return mixed The requested escaped value.
 360          */
 361         public function js_value() {
 362
 363                 /**
 364                  * Filter a Customize setting value for use in JavaScript.
 365                  *
 366                  * The dynamic portion of the hook name, `$this->id`, refers to the setting ID.
 367                  *
 368                  * @since 3.4.0
 369                  *
 370                  * @param mixed                $value The setting value.
 371                  * @param WP_Customize_Setting $this  {@see WP_Customize_Setting} instance.
 372                  */
 373                 $value = apply_filters( "customize_sanitize_js_{$this->id}", $this->value(), $this );
 374
 375                 if ( is_string( $value ) )
 376                         return html_entity_decode( $value, ENT_QUOTES, 'UTF-8');
 377
 378                 return $value;
 379         }
 380
 381         /**
 382          * Validate user capabilities whether the theme supports the setting.
 383          *
 384          * @since 3.4.0
 385          *
 386          * @return bool False if theme doesn't support the setting or user can't change setting, otherwise true.
 387          */
 388         public final function check_capabilities() {
 389                 if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) )
 390                         return false;
 391
 392                 if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) )
 393                         return false;
 394
 395                 return true;
 396         }
 397
 398         /**
 399          * Multidimensional helper function.
 400          *
 401          * @since 3.4.0
 402          *
 403          * @param $root
 404          * @param $keys
 405          * @param bool $create Default is false.
 406          * @return null|array Keys are 'root', 'node', and 'key'.
 407          */
 408         final protected function multidimensional( &$root, $keys, $create = false ) {
 409                 if ( $create && empty( $root ) )
 410                         $root = array();
 411
 412                 if ( ! isset( $root ) || empty( $keys ) )
 413                         return;
 414
 415                 $last = array_pop( $keys );
 416                 $node = &$root;
 417
 418                 foreach ( $keys as $key ) {
 419                         if ( $create && ! isset( $node[ $key ] ) )
 420                                 $node[ $key ] = array();
 421
 422                         if ( ! is_array( $node ) || ! isset( $node[ $key ] ) )
 423                                 return;
 424
 425                         $node = &$node[ $key ];
 426                 }
 427
 428                 if ( $create && ! isset( $node[ $last ] ) )
 429                         $node[ $last ] = array();
 430
 431                 if ( ! isset( $node[ $last ] ) )
 432                         return;
 433
 434                 return array(
 435                         'root' => &$root,
 436                         'node' => &$node,
 437                         'key'  => $last,
 438                 );
 439         }
 440
 441         /**
 442          * Will attempt to replace a specific value in a multidimensional array.
 443          *
 444          * @since 3.4.0
 445          *
 446          * @param $root
 447          * @param $keys
 448          * @param mixed $value The value to update.
 449          * @return
 450          */
 451         final protected function multidimensional_replace( $root, $keys, $value ) {
 452                 if ( ! isset( $value ) )
 453                         return $root;
 454                 elseif ( empty( $keys ) ) // If there are no keys, we're replacing the root.
 455                         return $value;
 456
 457                 $result = $this->multidimensional( $root, $keys, true );
 458
 459                 if ( isset( $result ) )
 460                         $result['node'][ $result['key'] ] = $value;
 461
 462                 return $root;
 463         }
 464
 465         /**
 466          * Will attempt to fetch a specific value from a multidimensional array.
 467          *
 468          * @since 3.4.0
 469          *
 470          * @param $root
 471          * @param $keys
 472          * @param mixed $default A default value which is used as a fallback. Default is null.
 473          * @return mixed The requested value or the default value.
 474          */
 475         final protected function multidimensional_get( $root, $keys, $default = null ) {
 476                 if ( empty( $keys ) ) // If there are no keys, test the root.
 477                         return isset( $root ) ? $root : $default;
 478
 479                 $result = $this->multidimensional( $root, $keys );
 480                 return isset( $result ) ? $result['node'][ $result['key'] ] : $default;
 481         }
 482
 483         /**
 484          * Will attempt to check if a specific value in a multidimensional array is set.
 485          *
 486          * @since 3.4.0
 487          *
 488          * @param $root
 489          * @param $keys
 490          * @return bool True if value is set, false if not.
 491          */
 492         final protected function multidimensional_isset( $root, $keys ) {
 493                 $result = $this->multidimensional_get( $root, $keys );
 494                 return isset( $result );
 495         }
 496 }
 497
 498 /**
 499  * A setting that is used to filter a value, but will not save the results.
 500  *
 501  * Results should be properly handled using another setting or callback.
 502  *
 503  * @package WordPress
 504  * @subpackage Customize
 505  * @since 3.4.0
 506  */
 507 class WP_Customize_Filter_Setting extends WP_Customize_Setting {
 508
 509         /**
 510          * @since 3.4.0
 511          */
 512         public function update( $value ) {}
 513 }
 514
 515 /**
 516  * A setting that is used to filter a value, but will not save the results.
 517  *
 518  * Results should be properly handled using another setting or callback.
 519  *
 520  * @package WordPress
 521  * @subpackage Customize
 522  * @since 3.4.0
 523  */
 524 final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
 525         public $id = 'header_image_data';
 526
 527         /**
 528          * @since 3.4.0
 529          *
 530          * @param $value
 531          */
 532         public function update( $value ) {
 533                 global $custom_image_header;
 534
 535                 // If the value doesn't exist (removed or random),
 536                 // use the header_image value.
 537                 if ( ! $value )
 538                         $value = $this->manager->get_setting('header_image')->post_value();
 539
 540                 if ( is_array( $value ) && isset( $value['choice'] ) )
 541                         $custom_image_header->set_header_image( $value['choice'] );
 542                 else
 543                         $custom_image_header->set_header_image( $value );
 544         }
 545 }
 546
 547 /**
 548  * Class WP_Customize_Background_Image_Setting
 549  *
 550  * @package WordPress
 551  * @subpackage Customize
 552  * @since 3.4.0
 553  */
 554 final class WP_Customize_Background_Image_Setting extends WP_Customize_Setting {
 555         public $id = 'background_image_thumb';
 556
 557         /**
 558          * @since 3.4.0
 559          *
 560          * @param $value
 561          */
 562         public function update( $value ) {
 563                 remove_theme_mod( 'background_image_thumb' );
 564         }
 565 }