WP_Customize_Setting

Customize Setting class.

Defined (1)

The class is defined in the following location(s).

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