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

  1. <?php 
  2. /** 
  3. * WordPress Customize Setting classes 
  4. * 
  5. * @package WordPress 
  6. * @subpackage Customize 
  7. * @since 3.4.0 
  8. */ 
  9.  
  10. /** 
  11. * Customize Setting class. 
  12. * 
  13. * Handles saving and sanitizing of settings. 
  14. * 
  15. * @since 3.4.0 
  16. * 
  17. * @see WP_Customize_Manager 
  18. */ 
  19. class WP_Customize_Setting { 
  20. /** 
  21. * @access public 
  22. * @var WP_Customize_Manager 
  23. */ 
  24. public $manager; 
  25.  
  26. /** 
  27. * Unique string identifier for the setting. 
  28. * 
  29. * @access public 
  30. * @var string 
  31. */ 
  32. public $id; 
  33.  
  34. /** 
  35. * @access public 
  36. * @var string 
  37. */ 
  38. public $type = 'theme_mod'; 
  39.  
  40. /** 
  41. * Capability required to edit this setting. 
  42. * 
  43. * @var string 
  44. */ 
  45. public $capability = 'edit_theme_options'; 
  46.  
  47. /** 
  48. * Feature a theme is required to support to enable this setting. 
  49. * 
  50. * @access public 
  51. * @var string 
  52. */ 
  53. public $theme_supports = ''; 
  54. public $default = ''; 
  55. public $transport = 'refresh'; 
  56.  
  57. /** 
  58. * Server-side sanitization callback for the setting's value. 
  59. * 
  60. * @var callback 
  61. */ 
  62. public $validate_callback = ''; 
  63. public $sanitize_callback = ''; 
  64. public $sanitize_js_callback = ''; 
  65.  
  66. /** 
  67. * Whether or not the setting is initially dirty when created. 
  68. * 
  69. * This is used to ensure that a setting will be sent from the pane to the 
  70. * preview when loading the Customizer. Normally a setting only is synced to 
  71. * the preview if it has been changed. This allows the setting to be sent 
  72. * from the start. 
  73. * 
  74. * @since 4.2.0 
  75. * @access public 
  76. * @var bool 
  77. */ 
  78. public $dirty = false; 
  79.  
  80. /** 
  81. * @var array 
  82. */ 
  83. protected $id_data = array(); 
  84.  
  85. /** 
  86. * Whether or not preview() was called. 
  87. * 
  88. * @since 4.4.0 
  89. * @access protected 
  90. * @var bool 
  91. */ 
  92. protected $is_previewed = false; 
  93.  
  94. /** 
  95. * Cache of multidimensional values to improve performance. 
  96. * 
  97. * @since 4.4.0 
  98. * @access protected 
  99. * @var array 
  100. * @static 
  101. */ 
  102. protected static $aggregated_multidimensionals = array(); 
  103.  
  104. /** 
  105. * Whether the multidimensional setting is aggregated. 
  106. * 
  107. * @since 4.4.0 
  108. * @access protected 
  109. * @var bool 
  110. */ 
  111. protected $is_multidimensional_aggregated = false; 
  112.  
  113. /** 
  114. * Constructor. 
  115. * 
  116. * Any supplied $args override class property defaults. 
  117. * 
  118. * @since 3.4.0 
  119. * 
  120. * @param WP_Customize_Manager $manager 
  121. * @param string $id An specific ID of the setting. Can be a 
  122. * theme mod or option name. 
  123. * @param array $args Setting arguments. 
  124. */ 
  125. public function __construct( $manager, $id, $args = array() ) { 
  126. $keys = array_keys( get_object_vars( $this ) ); 
  127. foreach ( $keys as $key ) { 
  128. if ( isset( $args[ $key ] ) ) { 
  129. $this->$key = $args[ $key ]; 
  130.  
  131. $this->manager = $manager; 
  132. $this->id = $id; 
  133.  
  134. // Parse the ID for array keys. 
  135. $this->id_data['keys'] = preg_split( '/\[/', str_replace( ']', '', $this->id ) ); 
  136. $this->id_data['base'] = array_shift( $this->id_data['keys'] ); 
  137.  
  138. // Rebuild the ID. 
  139. $this->id = $this->id_data[ 'base' ]; 
  140. if ( ! empty( $this->id_data[ 'keys' ] ) ) { 
  141. $this->id .= '[' . implode( '][', $this->id_data['keys'] ) . ']'; 
  142.  
  143. if ( $this->validate_callback ) { 
  144. add_filter( "customize_validate_{$this->id}", $this->validate_callback, 10, 3 ); 
  145. if ( $this->sanitize_callback ) { 
  146. add_filter( "customize_sanitize_{$this->id}", $this->sanitize_callback, 10, 2 ); 
  147. if ( $this->sanitize_js_callback ) { 
  148. add_filter( "customize_sanitize_js_{$this->id}", $this->sanitize_js_callback, 10, 2 ); 
  149.  
  150. if ( 'option' === $this->type || 'theme_mod' === $this->type ) { 
  151. // Other setting types can opt-in to aggregate multidimensional explicitly. 
  152. $this->aggregate_multidimensional(); 
  153.  
  154. // Allow option settings to indicate whether they should be autoloaded. 
  155. if ( 'option' === $this->type && isset( $args['autoload'] ) ) { 
  156. self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['autoload'] = $args['autoload']; 
  157.  
  158. /** 
  159. * Get parsed ID data for multidimensional setting. 
  160. * 
  161. * @since 4.4.0 
  162. * @access public 
  163. * 
  164. * @return array { 
  165. * ID data for multidimensional setting. 
  166. * 
  167. * @type string $base ID base 
  168. * @type array $keys Keys for multidimensional array. 
  169. * } 
  170. */ 
  171. final public function id_data() { 
  172. return $this->id_data; 
  173.  
  174. /** 
  175. * Set up the setting for aggregated multidimensional values. 
  176. * 
  177. * When a multidimensional setting gets aggregated, all of its preview and update 
  178. * calls get combined into one call, greatly improving performance. 
  179. * 
  180. * @since 4.4.0 
  181. * @access protected 
  182. */ 
  183. protected function aggregate_multidimensional() { 
  184. $id_base = $this->id_data['base']; 
  185. if ( ! isset( self::$aggregated_multidimensionals[ $this->type ] ) ) { 
  186. self::$aggregated_multidimensionals[ $this->type ] = array(); 
  187. if ( ! isset( self::$aggregated_multidimensionals[ $this->type ][ $id_base ] ) ) { 
  188. self::$aggregated_multidimensionals[ $this->type ][ $id_base ] = array( 
  189. 'previewed_instances' => array(), // Calling preview() will add the $setting to the array. 
  190. 'preview_applied_instances' => array(), // Flags for which settings have had their values applied. 
  191. 'root_value' => $this->get_root_value( array() ), // Root value for initial state, manipulated by preview and update calls. 
  192. ); 
  193.  
  194. if ( ! empty( $this->id_data['keys'] ) ) { 
  195. // Note the preview-applied flag is cleared at priority 9 to ensure it is cleared before a deferred-preview runs. 
  196. add_action( "customize_post_value_set_{$this->id}", array( $this, '_clear_aggregated_multidimensional_preview_applied_flag' ), 9 ); 
  197. $this->is_multidimensional_aggregated = true; 
  198.  
  199. /** 
  200. * Reset `$aggregated_multidimensionals` static variable. 
  201. * 
  202. * This is intended only for use by unit tests. 
  203. * 
  204. * @since 4.5.0 
  205. * @access public 
  206. * @ignore 
  207. */ 
  208. static public function reset_aggregated_multidimensionals() { 
  209. self::$aggregated_multidimensionals = array(); 
  210.  
  211. /** 
  212. * The ID for the current site when the preview() method was called. 
  213. * 
  214. * @since 4.2.0 
  215. * @access protected 
  216. * @var int 
  217. */ 
  218. protected $_previewed_blog_id; 
  219.  
  220. /** 
  221. * Return true if the current site is not the same as the previewed site. 
  222. * 
  223. * @since 4.2.0 
  224. * @access public 
  225. * 
  226. * @return bool If preview() has been called. 
  227. */ 
  228. public function is_current_blog_previewed() { 
  229. if ( ! isset( $this->_previewed_blog_id ) ) { 
  230. return false; 
  231. return ( get_current_blog_id() === $this->_previewed_blog_id ); 
  232.  
  233. /** 
  234. * Original non-previewed value stored by the preview method. 
  235. * 
  236. * @see WP_Customize_Setting::preview() 
  237. * @since 4.1.1 
  238. * @var mixed 
  239. */ 
  240. protected $_original_value; 
  241.  
  242. /** 
  243. * Add filters to supply the setting's value when accessed. 
  244. * 
  245. * If the setting already has a pre-existing value and there is no incoming 
  246. * post value for the setting, then this method will short-circuit since 
  247. * there is no change to preview. 
  248. * 
  249. * @since 3.4.0 
  250. * @since 4.4.0 Added boolean return value. 
  251. * @access public 
  252. * 
  253. * @return bool False when preview short-circuits due no change needing to be previewed. 
  254. */ 
  255. public function preview() { 
  256. if ( ! isset( $this->_previewed_blog_id ) ) { 
  257. $this->_previewed_blog_id = get_current_blog_id(); 
  258.  
  259. // Prevent re-previewing an already-previewed setting. 
  260. if ( $this->is_previewed ) { 
  261. return true; 
  262.  
  263. $id_base = $this->id_data['base']; 
  264. $is_multidimensional = ! empty( $this->id_data['keys'] ); 
  265. $multidimensional_filter = array( $this, '_multidimensional_preview_filter' ); 
  266.  
  267. /** 
  268. * Check if the setting has a pre-existing value (an isset check),  
  269. * and if doesn't have any incoming post value. If both checks are true,  
  270. * then the preview short-circuits because there is nothing that needs 
  271. * to be previewed. 
  272. */ 
  273. $undefined = new stdClass(); 
  274. $needs_preview = ( $undefined !== $this->post_value( $undefined ) ); 
  275. $value = null; 
  276.  
  277. // Since no post value was defined, check if we have an initial value set. 
  278. if ( ! $needs_preview ) { 
  279. if ( $this->is_multidimensional_aggregated ) { 
  280. $root = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; 
  281. $value = $this->multidimensional_get( $root, $this->id_data['keys'], $undefined ); 
  282. } else { 
  283. $default = $this->default; 
  284. $this->default = $undefined; // Temporarily set default to undefined so we can detect if existing value is set. 
  285. $value = $this->value(); 
  286. $this->default = $default; 
  287. $needs_preview = ( $undefined === $value ); // Because the default needs to be supplied. 
  288.  
  289. // If the setting does not need previewing now, defer to when it has a value to preview. 
  290. if ( ! $needs_preview ) { 
  291. if ( ! has_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) ) ) { 
  292. add_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) ); 
  293. return false; 
  294.  
  295. switch ( $this->type ) { 
  296. case 'theme_mod' : 
  297. if ( ! $is_multidimensional ) { 
  298. add_filter( "theme_mod_{$id_base}", array( $this, '_preview_filter' ) ); 
  299. } else { 
  300. if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) { 
  301. // Only add this filter once for this ID base. 
  302. add_filter( "theme_mod_{$id_base}", $multidimensional_filter ); 
  303. self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this; 
  304. break; 
  305. case 'option' : 
  306. if ( ! $is_multidimensional ) { 
  307. add_filter( "pre_option_{$id_base}", array( $this, '_preview_filter' ) ); 
  308. } else { 
  309. if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) { 
  310. // Only add these filters once for this ID base. 
  311. add_filter( "option_{$id_base}", $multidimensional_filter ); 
  312. add_filter( "default_option_{$id_base}", $multidimensional_filter ); 
  313. self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this; 
  314. break; 
  315. default : 
  316.  
  317. /** 
  318. * Fires when the WP_Customize_Setting::preview() method is called for settings 
  319. * not handled as theme_mods or options. 
  320. * 
  321. * The dynamic portion of the hook name, `$this->id`, refers to the setting ID. 
  322. * 
  323. * @since 3.4.0 
  324. * 
  325. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  326. */ 
  327. do_action( "customize_preview_{$this->id}", $this ); 
  328.  
  329. /** 
  330. * Fires when the WP_Customize_Setting::preview() method is called for settings 
  331. * not handled as theme_mods or options. 
  332. * 
  333. * The dynamic portion of the hook name, `$this->type`, refers to the setting type. 
  334. * 
  335. * @since 4.1.0 
  336. * 
  337. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  338. */ 
  339. do_action( "customize_preview_{$this->type}", $this ); 
  340.  
  341. $this->is_previewed = true; 
  342.  
  343. return true; 
  344.  
  345. /** 
  346. * Clear out the previewed-applied flag for a multidimensional-aggregated value whenever its post value is updated. 
  347. * 
  348. * This ensures that the new value will get sanitized and used the next time 
  349. * that `WP_Customize_Setting::_multidimensional_preview_filter()` 
  350. * is called for this setting. 
  351. * 
  352. * @since 4.4.0 
  353. * @access private 
  354. * @see WP_Customize_Manager::set_post_value() 
  355. * @see WP_Customize_Setting::_multidimensional_preview_filter() 
  356. */ 
  357. final public function _clear_aggregated_multidimensional_preview_applied_flag() { 
  358. unset( self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['preview_applied_instances'][ $this->id ] ); 
  359.  
  360. /** 
  361. * Callback function to filter non-multidimensional theme mods and options. 
  362. * 
  363. * If switch_to_blog() was called after the preview() method, and the current 
  364. * site is now not the same site, then this method does a no-op and returns 
  365. * the original value. 
  366. * 
  367. * @since 3.4.0 
  368. * 
  369. * @param mixed $original Old value. 
  370. * @return mixed New or old value. 
  371. */ 
  372. public function _preview_filter( $original ) { 
  373. if ( ! $this->is_current_blog_previewed() ) { 
  374. return $original; 
  375.  
  376. $undefined = new stdClass(); // Symbol hack. 
  377. $post_value = $this->post_value( $undefined ); 
  378. if ( $undefined !== $post_value ) { 
  379. $value = $post_value; 
  380. } else { 
  381. /** 
  382. * Note that we don't use $original here because preview() will 
  383. * not add the filter in the first place if it has an initial value 
  384. * and there is no post value. 
  385. */ 
  386. $value = $this->default; 
  387. return $value; 
  388.  
  389. /** 
  390. * Callback function to filter multidimensional theme mods and options. 
  391. * 
  392. * For all multidimensional settings of a given type, the preview filter for 
  393. * the first setting previewed will be used to apply the values for the others. 
  394. * 
  395. * @since 4.4.0 
  396. * @access private 
  397. * 
  398. * @see WP_Customize_Setting::$aggregated_multidimensionals 
  399. * @param mixed $original Original root value. 
  400. * @return mixed New or old value. 
  401. */ 
  402. final public function _multidimensional_preview_filter( $original ) { 
  403. if ( ! $this->is_current_blog_previewed() ) { 
  404. return $original; 
  405.  
  406. $id_base = $this->id_data['base']; 
  407.  
  408. // If no settings have been previewed yet (which should not be the case, since $this is), just pass through the original value. 
  409. if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) { 
  410. return $original; 
  411.  
  412. foreach ( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] as $previewed_setting ) { 
  413. // Skip applying previewed value for any settings that have already been applied. 
  414. if ( ! empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['preview_applied_instances'][ $previewed_setting->id ] ) ) { 
  415. continue; 
  416.  
  417. // Do the replacements of the posted/default sub value into the root value. 
  418. $value = $previewed_setting->post_value( $previewed_setting->default ); 
  419. $root = self::$aggregated_multidimensionals[ $previewed_setting->type ][ $id_base ]['root_value']; 
  420. $root = $previewed_setting->multidimensional_replace( $root, $previewed_setting->id_data['keys'], $value ); 
  421. self::$aggregated_multidimensionals[ $previewed_setting->type ][ $id_base ]['root_value'] = $root; 
  422.  
  423. // Mark this setting having been applied so that it will be skipped when the filter is called again. 
  424. self::$aggregated_multidimensionals[ $previewed_setting->type ][ $id_base ]['preview_applied_instances'][ $previewed_setting->id ] = true; 
  425.  
  426. return self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; 
  427.  
  428. /** 
  429. * Checks user capabilities and theme supports, and then saves 
  430. * the value of the setting. 
  431. * 
  432. * @since 3.4.0 
  433. * 
  434. * @access public 
  435. * 
  436. * @return false|void False if cap check fails or value isn't set or is invalid. 
  437. */ 
  438. final public function save() { 
  439. $value = $this->post_value(); 
  440.  
  441. if ( ! $this->check_capabilities() || ! isset( $value ) ) { 
  442. return false; 
  443.  
  444. /** 
  445. * Fires when the WP_Customize_Setting::save() method is called. 
  446. * 
  447. * The dynamic portion of the hook name, `$this->id_data['base']` refers to 
  448. * the base slug of the setting name. 
  449. * 
  450. * @since 3.4.0 
  451. * 
  452. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  453. */ 
  454. do_action( 'customize_save_' . $this->id_data['base'], $this ); 
  455.  
  456. $this->update( $value ); 
  457.  
  458. /** 
  459. * Fetch and sanitize the $_POST value for the setting. 
  460. * 
  461. * During a save request prior to save, post_value() provides the new value while value() does not. 
  462. * 
  463. * @since 3.4.0 
  464. * 
  465. * @param mixed $default A default value which is used as a fallback. Default is null. 
  466. * @return mixed The default value on failure, otherwise the sanitized and validated value. 
  467. */ 
  468. final public function post_value( $default = null ) { 
  469. return $this->manager->post_value( $this, $default ); 
  470.  
  471. /** 
  472. * Sanitize an input. 
  473. * 
  474. * @since 3.4.0 
  475. * 
  476. * @param string|array $value The value to sanitize. 
  477. * @return string|array|null|WP_Error Sanitized value, or `null`/`WP_Error` if invalid. 
  478. */ 
  479. public function sanitize( $value ) { 
  480.  
  481. /** 
  482. * Filters a Customize setting value in un-slashed form. 
  483. * 
  484. * @since 3.4.0 
  485. * 
  486. * @param mixed $value Value of the setting. 
  487. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  488. */ 
  489. return apply_filters( "customize_sanitize_{$this->id}", $value, $this ); 
  490.  
  491. /** 
  492. * Validates an input. 
  493. * 
  494. * @since 4.6.0 
  495. * @access public 
  496. * 
  497. * @see WP_REST_Request::has_valid_params() 
  498. * 
  499. * @param mixed $value Value to validate. 
  500. * @return true|WP_Error True if the input was validated, otherwise WP_Error. 
  501. */ 
  502. public function validate( $value ) { 
  503. if ( is_wp_error( $value ) ) { 
  504. return $value; 
  505. if ( is_null( $value ) ) { 
  506. return new WP_Error( 'invalid_value', __( 'Invalid value.' ) ); 
  507.  
  508. $validity = new WP_Error(); 
  509.  
  510. /** 
  511. * Validates a Customize setting value. 
  512. * 
  513. * Plugins should amend the `$validity` object via its `WP_Error::add()` method. 
  514. * 
  515. * The dynamic portion of the hook name, `$this->ID`, refers to the setting ID. 
  516. * 
  517. * @since 4.6.0 
  518. * 
  519. * @param WP_Error $validity Filtered from `true` to `WP_Error` when invalid. 
  520. * @param mixed $value Value of the setting. 
  521. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  522. */ 
  523. $validity = apply_filters( "customize_validate_{$this->id}", $validity, $value, $this ); 
  524.  
  525. if ( is_wp_error( $validity ) && empty( $validity->errors ) ) { 
  526. $validity = true; 
  527. return $validity; 
  528.  
  529. /** 
  530. * Get the root value for a setting, especially for multidimensional ones. 
  531. * 
  532. * @since 4.4.0 
  533. * @access protected 
  534. * 
  535. * @param mixed $default Value to return if root does not exist. 
  536. * @return mixed 
  537. */ 
  538. protected function get_root_value( $default = null ) { 
  539. $id_base = $this->id_data['base']; 
  540. if ( 'option' === $this->type ) { 
  541. return get_option( $id_base, $default ); 
  542. } elseif ( 'theme_mod' === $this->type ) { 
  543. return get_theme_mod( $id_base, $default ); 
  544. } else { 
  545. /** 
  546. * Any WP_Customize_Setting subclass implementing aggregate multidimensional 
  547. * will need to override this method to obtain the data from the appropriate 
  548. * location. 
  549. */ 
  550. return $default; 
  551.  
  552. /** 
  553. * Set the root value for a setting, especially for multidimensional ones. 
  554. * 
  555. * @since 4.4.0 
  556. * @access protected 
  557. * 
  558. * @param mixed $value Value to set as root of multidimensional setting. 
  559. * @return bool Whether the multidimensional root was updated successfully. 
  560. */ 
  561. protected function set_root_value( $value ) { 
  562. $id_base = $this->id_data['base']; 
  563. if ( 'option' === $this->type ) { 
  564. $autoload = true; 
  565. if ( isset( self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['autoload'] ) ) { 
  566. $autoload = self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['autoload']; 
  567. return update_option( $id_base, $value, $autoload ); 
  568. } elseif ( 'theme_mod' === $this->type ) { 
  569. set_theme_mod( $id_base, $value ); 
  570. return true; 
  571. } else { 
  572. /** 
  573. * Any WP_Customize_Setting subclass implementing aggregate multidimensional 
  574. * will need to override this method to obtain the data from the appropriate 
  575. * location. 
  576. */ 
  577. return false; 
  578.  
  579. /** 
  580. * Save the value of the setting, using the related API. 
  581. * 
  582. * @since 3.4.0 
  583. * 
  584. * @param mixed $value The value to update. 
  585. * @return bool The result of saving the value. 
  586. */ 
  587. protected function update( $value ) { 
  588. $id_base = $this->id_data['base']; 
  589. if ( 'option' === $this->type || 'theme_mod' === $this->type ) { 
  590. if ( ! $this->is_multidimensional_aggregated ) { 
  591. return $this->set_root_value( $value ); 
  592. } else { 
  593. $root = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; 
  594. $root = $this->multidimensional_replace( $root, $this->id_data['keys'], $value ); 
  595. self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value'] = $root; 
  596. return $this->set_root_value( $root ); 
  597. } else { 
  598. /** 
  599. * Fires when the WP_Customize_Setting::update() method is called for settings 
  600. * not handled as theme_mods or options. 
  601. * 
  602. * The dynamic portion of the hook name, `$this->type`, refers to the type of setting. 
  603. * 
  604. * @since 3.4.0 
  605. * 
  606. * @param mixed $value Value of the setting. 
  607. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  608. */ 
  609. do_action( "customize_update_{$this->type}", $value, $this ); 
  610.  
  611. return has_action( "customize_update_{$this->type}" ); 
  612.  
  613. /** 
  614. * Deprecated method. 
  615. * 
  616. * @since 3.4.0 
  617. * @deprecated 4.4.0 Deprecated in favor of update() method. 
  618. */ 
  619. protected function _update_theme_mod() { 
  620. _deprecated_function( __METHOD__, '4.4.0', __CLASS__ . '::update()' ); 
  621.  
  622. /** 
  623. * Deprecated method. 
  624. * 
  625. * @since 3.4.0 
  626. * @deprecated 4.4.0 Deprecated in favor of update() method. 
  627. */ 
  628. protected function _update_option() { 
  629. _deprecated_function( __METHOD__, '4.4.0', __CLASS__ . '::update()' ); 
  630.  
  631. /** 
  632. * Fetch the value of the setting. 
  633. * 
  634. * @since 3.4.0 
  635. * 
  636. * @return mixed The value. 
  637. */ 
  638. public function value() { 
  639. $id_base = $this->id_data['base']; 
  640. $is_core_type = ( 'option' === $this->type || 'theme_mod' === $this->type ); 
  641.  
  642. if ( ! $is_core_type && ! $this->is_multidimensional_aggregated ) { 
  643.  
  644. // Use post value if previewed and a post value is present. 
  645. if ( $this->is_previewed ) { 
  646. $value = $this->post_value( null ); 
  647. if ( null !== $value ) { 
  648. return $value; 
  649.  
  650. $value = $this->get_root_value( $this->default ); 
  651.  
  652. /** 
  653. * Filters a Customize setting value not handled as a theme_mod or option. 
  654. * 
  655. * The dynamic portion of the hook name, `$id_base`, refers to 
  656. * the base slug of the setting name, initialized from `$this->id_data['base']`. 
  657. * 
  658. * For settings handled as theme_mods or options, see those corresponding 
  659. * functions for available hooks. 
  660. * 
  661. * @since 3.4.0 
  662. * @since 4.6.0 Added the `$this` setting instance as the second parameter. 
  663. * 
  664. * @param mixed $default The setting default value. Default empty. 
  665. * @param WP_Customize_Setting $this The setting instance. 
  666. */ 
  667. $value = apply_filters( "customize_value_{$id_base}", $value, $this ); 
  668. } elseif ( $this->is_multidimensional_aggregated ) { 
  669. $root_value = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value']; 
  670. $value = $this->multidimensional_get( $root_value, $this->id_data['keys'], $this->default ); 
  671.  
  672. // Ensure that the post value is used if the setting is previewed, since preview filters aren't applying on cached $root_value. 
  673. if ( $this->is_previewed ) { 
  674. $value = $this->post_value( $value ); 
  675. } else { 
  676. $value = $this->get_root_value( $this->default ); 
  677. return $value; 
  678.  
  679. /** 
  680. * Sanitize the setting's value for use in JavaScript. 
  681. * 
  682. * @since 3.4.0 
  683. * 
  684. * @return mixed The requested escaped value. 
  685. */ 
  686. public function js_value() { 
  687.  
  688. /** 
  689. * Filters a Customize setting value for use in JavaScript. 
  690. * 
  691. * The dynamic portion of the hook name, `$this->id`, refers to the setting ID. 
  692. * 
  693. * @since 3.4.0 
  694. * 
  695. * @param mixed $value The setting value. 
  696. * @param WP_Customize_Setting $this WP_Customize_Setting instance. 
  697. */ 
  698. $value = apply_filters( "customize_sanitize_js_{$this->id}", $this->value(), $this ); 
  699.  
  700. if ( is_string( $value ) ) 
  701. return html_entity_decode( $value, ENT_QUOTES, 'UTF-8'); 
  702.  
  703. return $value; 
  704.  
  705. /** 
  706. * Retrieves the data to export to the client via JSON. 
  707. * 
  708. * @since 4.6.0 
  709. * @access public 
  710. * 
  711. * @return array Array of parameters passed to JavaScript. 
  712. */ 
  713. public function json() { 
  714. return array( 
  715. 'value' => $this->js_value(),  
  716. 'transport' => $this->transport,  
  717. 'dirty' => $this->dirty,  
  718. 'type' => $this->type,  
  719. ); 
  720.  
  721. /** 
  722. * Validate user capabilities whether the theme supports the setting. 
  723. * 
  724. * @since 3.4.0 
  725. * 
  726. * @return bool False if theme doesn't support the setting or user can't change setting, otherwise true. 
  727. */ 
  728. final public function check_capabilities() { 
  729. if ( $this->capability && ! call_user_func_array( 'current_user_can', (array) $this->capability ) ) 
  730. return false; 
  731.  
  732. if ( $this->theme_supports && ! call_user_func_array( 'current_theme_supports', (array) $this->theme_supports ) ) 
  733. return false; 
  734.  
  735. return true; 
  736.  
  737. /** 
  738. * Multidimensional helper function. 
  739. * 
  740. * @since 3.4.0 
  741. * 
  742. * @param $root 
  743. * @param $keys 
  744. * @param bool $create Default is false. 
  745. * @return array|void Keys are 'root', 'node', and 'key'. 
  746. */ 
  747. final protected function multidimensional( &$root, $keys, $create = false ) { 
  748. if ( $create && empty( $root ) ) 
  749. $root = array(); 
  750.  
  751. if ( ! isset( $root ) || empty( $keys ) ) 
  752. return; 
  753.  
  754. $last = array_pop( $keys ); 
  755. $node = &$root; 
  756.  
  757. foreach ( $keys as $key ) { 
  758. if ( $create && ! isset( $node[ $key ] ) ) 
  759. $node[ $key ] = array(); 
  760.  
  761. if ( ! is_array( $node ) || ! isset( $node[ $key ] ) ) 
  762. return; 
  763.  
  764. $node = &$node[ $key ]; 
  765.  
  766. if ( $create ) { 
  767. if ( ! is_array( $node ) ) { 
  768. // account for an array overriding a string or object value 
  769. $node = array(); 
  770. if ( ! isset( $node[ $last ] ) ) { 
  771. $node[ $last ] = array(); 
  772.  
  773. if ( ! isset( $node[ $last ] ) ) 
  774. return; 
  775.  
  776. return array( 
  777. 'root' => &$root,  
  778. 'node' => &$node,  
  779. 'key' => $last,  
  780. ); 
  781.  
  782. /** 
  783. * Will attempt to replace a specific value in a multidimensional array. 
  784. * 
  785. * @since 3.4.0 
  786. * 
  787. * @param $root 
  788. * @param $keys 
  789. * @param mixed $value The value to update. 
  790. * @return mixed 
  791. */ 
  792. final protected function multidimensional_replace( $root, $keys, $value ) { 
  793. if ( ! isset( $value ) ) 
  794. return $root; 
  795. elseif ( empty( $keys ) ) // If there are no keys, we're replacing the root. 
  796. return $value; 
  797.  
  798. $result = $this->multidimensional( $root, $keys, true ); 
  799.  
  800. if ( isset( $result ) ) 
  801. $result['node'][ $result['key'] ] = $value; 
  802.  
  803. return $root; 
  804.  
  805. /** 
  806. * Will attempt to fetch a specific value from a multidimensional array. 
  807. * 
  808. * @since 3.4.0 
  809. * 
  810. * @param $root 
  811. * @param $keys 
  812. * @param mixed $default A default value which is used as a fallback. Default is null. 
  813. * @return mixed The requested value or the default value. 
  814. */ 
  815. final protected function multidimensional_get( $root, $keys, $default = null ) { 
  816. if ( empty( $keys ) ) // If there are no keys, test the root. 
  817. return isset( $root ) ? $root : $default; 
  818.  
  819. $result = $this->multidimensional( $root, $keys ); 
  820. return isset( $result ) ? $result['node'][ $result['key'] ] : $default; 
  821.  
  822. /** 
  823. * Will attempt to check if a specific value in a multidimensional array is set. 
  824. * 
  825. * @since 3.4.0 
  826. * 
  827. * @param $root 
  828. * @param $keys 
  829. * @return bool True if value is set, false if not. 
  830. */ 
  831. final protected function multidimensional_isset( $root, $keys ) { 
  832. $result = $this->multidimensional_get( $root, $keys ); 
  833. return isset( $result ); 
  834.  
  835. /** WP_Customize_Filter_Setting class */ 
  836. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-filter-setting.php' ); 
  837.  
  838. /** WP_Customize_Header_Image_Setting class */ 
  839. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-header-image-setting.php' ); 
  840.  
  841. /** WP_Customize_Background_Image_Setting class */ 
  842. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-background-image-setting.php' ); 
  843.  
  844. /** WP_Customize_Nav_Menu_Item_Setting class */ 
  845. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-item-setting.php' ); 
  846.  
  847. /** WP_Customize_Nav_Menu_Setting class */ 
  848. require_once( ABSPATH . WPINC . '/customize/class-wp-customize-nav-menu-setting.php' ); 
.