Class: WP_Customize_Setting

Customize Setting class.

Handles saving and sanitizing of settings.


Properties

Name Type(s) Default Value Summary
manager WP_Customize_Manager Customizer bootstrap instance.
id string Unique string identifier for the setting.
type string Type of customize settings.
capability string | array Capability required to edit this setting.
theme_supports string Feature a theme is required to support to enable this setting.
default string The default value for the setting.
transport string Options for rendering the live preview of changes in Theme Customizer.

Set this value to 'postMessage' to enable a custom Javascript handler to render changes to this setting as opposed to reloading the whole page.

validate_callback callable Server-side validation callback for the setting's value.
sanitize_callback callable Callback to filter a Customize setting value in un-slashed form.
sanitize_js_callback string Callback to convert a Customize PHP setting value to a value that is JSON serializable.
dirty boolean Whether or not the setting is initially dirty when created.

This is used to ensure that a setting will be sent from the pane to the preview when loading the Customizer. Normally a setting only is synced to the preview if it has been changed. This allows the setting to be sent from the start.

id_data array ID Data.
is_previewed boolean Whether or not preview() was called.
aggregated_multidimensionals array Static ⋅ Cache of multidimensional values to improve performance.
is_multidimensional_aggregated boolean Whether the multidimensional setting is aggregated.
_previewed_blog_id integer The ID for the current site when the preview() method was called.
_original_value mixed Original non-previewed value stored by the preview method.

Methods

WP_Customize_Setting:: __construct( WP_Customize_Manager $manager, string $id, array $args = array() )

Constructor. Since 3.4.0.

Any supplied $args override class property defaults.

Arguments

Name Type(s) Default Value Description
$manager WP_Customize_Manager
$id string

An specific ID of the setting. Can be a theme mod or option name.

$args array

Setting arguments.


WP_Customize_Setting:: _clear_aggregated_multidimensional_preview_applied_flag( )

Clear out the previewed-applied flag for a multidimensional-aggregated value whenever its post value is updated. Since 4.4.0.

This ensures that the new value will get sanitized and used the next time that WP_Customize_Setting::_multidimensional_preview_filter() is called for this setting.


WP_Customize_Setting:: _multidimensional_preview_filter( mixed $original )

Callback function to filter multidimensional theme mods and options. Since 4.4.0.

For all multidimensional settings of a given type, the preview filter for the first setting previewed will be used to apply the values for the others.

Arguments

Name Type(s) Default Value Description
$original mixed

Original root value.

Returns

mixed

New or old value.


WP_Customize_Setting:: _preview_filter( mixed $original )

Callback function to filter non-multidimensional theme mods and options. Since 3.4.0.

If switch_to_blog() was called after the preview() method, and the current site is now not the same site, then this method does a no-op and returns the original value.

Arguments

Name Type(s) Default Value Description
$original mixed

Old value.

Returns

mixed

New or old value.


WP_Customize_Setting:: _update_option( )

This method is deprecated.

Deprecated method. Since 3.4.0.


WP_Customize_Setting:: _update_theme_mod( )

This method is deprecated.

Deprecated method. Since 3.4.0.


WP_Customize_Setting:: aggregate_multidimensional( )

Set up the setting for aggregated multidimensional values. Since 4.4.0.

When a multidimensional setting gets aggregated, all of its preview and update calls get combined into one call, greatly improving performance.


WP_Customize_Setting:: check_capabilities( )

Validate user capabilities whether the theme supports the setting. Since 3.4.0.

Returns

boolean

False if theme doesn't support the setting or user can't change setting, otherwise true.


WP_Customize_Setting:: get_root_value( mixed $default = null )

Get the root value for a setting, especially for multidimensional ones. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$default mixed

Value to return if root does not exist.

Returns

mixed


WP_Customize_Setting:: id_data( )

Get parsed ID data for multidimensional setting. Since 4.4.0.

Returns

array

{ ID data for multidimensional setting.

@type string $base ID base
@type array  $keys Keys for multidimensional array.

}


WP_Customize_Setting:: is_current_blog_previewed( )

Return true if the current site is not the same as the previewed site. Since 4.2.0.

Returns

boolean

If preview() has been called.


WP_Customize_Setting:: js_value( )

Sanitize the setting's value for use in JavaScript. Since 3.4.0.

Returns

mixed

The requested escaped value.


WP_Customize_Setting:: json( )

Retrieves the data to export to the client via JSON. Since 4.6.0.

Returns

array

Array of parameters passed to JavaScript.


WP_Customize_Setting:: multidimensional( &$root, $keys, boolean $create = false )

Multidimensional helper function. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$create boolean

Default is false.

Returns

array | void

Keys are 'root', 'node', and 'key'.


WP_Customize_Setting:: multidimensional_get( $root, $keys, mixed $default = null )

Will attempt to fetch a specific value from a multidimensional array. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$default mixed

A default value which is used as a fallback. Default is null.

Returns

mixed

The requested value or the default value.


WP_Customize_Setting:: multidimensional_isset( $root, $keys )

Will attempt to check if a specific value in a multidimensional array is set. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys

Returns

boolean

True if value is set, false if not.


WP_Customize_Setting:: multidimensional_replace( $root, $keys, mixed $value )

Will attempt to replace a specific value in a multidimensional array. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$value mixed

The value to update.

Returns

mixed


WP_Customize_Setting:: post_value( mixed $default = null )

Fetch and sanitize the $_POST value for the setting. Since 3.4.0.

During a save request prior to save, post_value() provides the new value while value() does not.

Arguments

Name Type(s) Default Value Description
$default mixed

A default value which is used as a fallback. Default is null.

Returns

mixed

The default value on failure, otherwise the sanitized and validated value.


WP_Customize_Setting:: preview( )

Add filters to supply the setting's value when accessed. Since 3.4.0. Since 4.4.0.

If the setting already has a pre-existing value and there is no incoming post value for the setting, then this method will short-circuit since there is no change to preview.

Returns

boolean

False when preview short-circuits due no change needing to be previewed.


WP_Customize_Setting:: sanitize( string | array $value )

Sanitize an input. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$value string | array

The value to sanitize.

Returns

string | array | null | WP_Error

Sanitized value, or null/WP_Error if invalid.


WP_Customize_Setting:: save( )

Checks user capabilities and theme supports, and then saves the value of the setting. Since 3.4.0.

Returns

false | void

False if cap check fails or value isn't set or is invalid.


WP_Customize_Setting:: set_root_value( mixed $value )

Set the root value for a setting, especially for multidimensional ones. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Value to set as root of multidimensional setting.

Returns

boolean

Whether the multidimensional root was updated successfully.


WP_Customize_Setting:: update( mixed $value )

Save the value of the setting, using the related API. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$value mixed

The value to update.

Returns

boolean

The result of saving the value.


WP_Customize_Setting:: validate( mixed $value )

Validates an input. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Value to validate.

Returns

true | WP_Error

True if the input was validated, otherwise WP_Error.


WP_Customize_Setting:: value( )

Fetch the value of the setting. Since 3.4.0.

Returns

mixed

The value.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.