PHP Class WP_Customize_Setting, wordpress

Handles saving and sanitizing of settings.
See also: WP_Customize_Manager
Since: 3.4.0
Inheritance: extends WP_Fields_API_Field
Mostrar archivo Open project: johnpbloch/wordpress Class Usage Examples

Public Properties

Property Type Description
$capability string Capability required to edit this setting.
$default
$dirty boolean 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 string Unique string identifier for the setting.
$manager WP_Customize_Manager
$sanitize_callback
$sanitize_js_callback
$theme_supports string Feature a theme is required to support to enable this setting.
$transport
$type string
$validate_callback callback Server-side sanitization callback for the setting's value.

Protected Properties

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

Public Methods

Method Description
__construct ( WP_Customize_Manager $manager, string $id, array $args = [] ) Constructor.
_clear_aggregated_multidimensional_preview_applied_flag ( ) Clear out the previewed-applied flag for a multidimensional-aggregated value whenever its post value is updated.
_multidimensional_preview_filter ( mixed $original ) : mixed Callback function to filter multidimensional theme mods and options.
_preview_filter ( mixed $original ) : mixed Callback function to filter non-multidimensional theme mods and options.
check_capabilities ( ) : boolean Validate user capabilities whether the theme supports the setting.
id_data ( ) : array Get parsed ID data for multidimensional setting.
is_current_blog_previewed ( ) : boolean Return true if the current site is not the same as the previewed site.
js_value ( ) : mixed Sanitize the setting's value for use in JavaScript.
json ( ) : array Retrieves the data to export to the client via JSON.
post_value ( mixed $default = null ) : mixed Fetch and sanitize the $_POST value for the setting.
preview ( ) : boolean Add filters to supply the setting's value when accessed.
reset_aggregated_multidimensionals ( ) Reset $aggregated_multidimensionals static variable.
sanitize ( string | array $value ) : string | array | null | WP_Error Sanitize an input.
save ( ) : false | void Checks user capabilities and theme supports, and then saves the value of the setting.
validate ( mixed $value ) : true | WP_Error Validates an input.
value ( ) : mixed Fetch the value of the setting.

Protected Methods

Method Description
_update_option ( ) Deprecated method.
_update_theme_mod ( ) Deprecated method.
aggregate_multidimensional ( ) Set up the setting for aggregated multidimensional values.
get_root_value ( mixed $default = null ) : mixed Get the root value for a setting, especially for multidimensional ones.
multidimensional ( &$root, $keys, boolean $create = false ) : array | void Multidimensional helper function.
multidimensional_get ( $root, $keys, mixed $default = null ) : mixed Will attempt to fetch a specific value from a multidimensional array.
multidimensional_isset ( $root, $keys ) : boolean Will attempt to check if a specific value in a multidimensional array is set.
multidimensional_replace ( $root, $keys, mixed $value ) : mixed Will attempt to replace a specific value in a multidimensional array.
set_root_value ( mixed $value ) : boolean Set the root value for a setting, especially for multidimensional ones.
update ( mixed $value ) : boolean Save the value of the setting, using the related API.

Method Details

__construct() public method

Any supplied $args override class property defaults.
Since: 3.4.0
public __construct ( WP_Customize_Manager $manager, string $id, array $args = [] )
$manager WP_Customize_Manager
$id string An specific ID of the setting. Can be a theme mod or option name.
$args array Setting arguments.

_clear_aggregated_multidimensional_preview_applied_flag() final public method

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.
See also: WP_Customize_Manager::set_post_value()
See also: WP_Customize_Setting::_multidimensional_preview_filter()
Since: 4.4.0

_multidimensional_preview_filter() final public method

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.
See also: WP_Customize_Setting::$aggregated_multidimensionals
Since: 4.4.0
final public _multidimensional_preview_filter ( mixed $original ) : mixed
$original mixed Original root value.
return mixed New or old value.

_preview_filter() public method

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.
Since: 3.4.0
public _preview_filter ( mixed $original ) : mixed
$original mixed Old value.
return mixed New or old value.

_update_option() protected method

Deprecated method.
Deprecation: 4.4.0 Deprecated in favor of update() method.
Since: 3.4.0
protected _update_option ( )

_update_theme_mod() protected method

Deprecated method.
Deprecation: 4.4.0 Deprecated in favor of update() method.
Since: 3.4.0
protected _update_theme_mod ( )

aggregate_multidimensional() protected method

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

check_capabilities() final public method

Validate user capabilities whether the theme supports the setting.
Since: 3.4.0
final public check_capabilities ( ) : boolean
return boolean False if theme doesn't support the setting or user can't change setting, otherwise true.

get_root_value() protected method

Get the root value for a setting, especially for multidimensional ones.
Since: 4.4.0
protected get_root_value ( mixed $default = null ) : mixed
$default mixed Value to return if root does not exist.
return mixed

id_data() final public method

Get parsed ID data for multidimensional setting.
Since: 4.4.0
final public id_data ( ) : array
return array { ID data for multidimensional setting. @type string $base ID base @type array $keys Keys for multidimensional array. }

is_current_blog_previewed() public method

Return true if the current site is not the same as the previewed site.
Since: 4.2.0
public is_current_blog_previewed ( ) : boolean
return boolean If preview() has been called.

js_value() public method

Sanitize the setting's value for use in JavaScript.
Since: 3.4.0
public js_value ( ) : mixed
return mixed The requested escaped value.

json() public method

Retrieves the data to export to the client via JSON.
Since: 4.6.0
public json ( ) : array
return array Array of parameters passed to JavaScript.

multidimensional() final protected method

Multidimensional helper function.
Since: 3.4.0
final protected multidimensional ( &$root, $keys, boolean $create = false ) : array | void
$root
$keys
$create boolean Default is false.
return array | void Keys are 'root', 'node', and 'key'.

multidimensional_get() final protected method

Will attempt to fetch a specific value from a multidimensional array.
Since: 3.4.0
final protected multidimensional_get ( $root, $keys, mixed $default = null ) : mixed
$root
$keys
$default mixed A default value which is used as a fallback. Default is null.
return mixed The requested value or the default value.

multidimensional_isset() final protected method

Will attempt to check if a specific value in a multidimensional array is set.
Since: 3.4.0
final protected multidimensional_isset ( $root, $keys ) : boolean
$root
$keys
return boolean True if value is set, false if not.

multidimensional_replace() final protected method

Will attempt to replace a specific value in a multidimensional array.
Since: 3.4.0
final protected multidimensional_replace ( $root, $keys, mixed $value ) : mixed
$root
$keys
$value mixed The value to update.
return mixed

post_value() final public method

During a save request prior to save, post_value() provides the new value while value() does not.
Since: 3.4.0
final public post_value ( mixed $default = null ) : mixed
$default mixed A default value which is used as a fallback. Default is null.
return mixed The default value on failure, otherwise the sanitized and validated value.

preview() public method

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.
Since: 3.4.0
Since: 4.4.0 Added boolean return value.
public preview ( ) : boolean
return boolean False when preview short-circuits due no change needing to be previewed.

reset_aggregated_multidimensionals() public static method

This is intended only for use by unit tests.
Since: 4.5.0

sanitize() public method

Sanitize an input.
Since: 3.4.0
public sanitize ( string | array $value ) : string | array | null | WP_Error
$value string | array The value to sanitize.
return string | array | null | WP_Error Sanitized value, or `null`/`WP_Error` if invalid.

save() final public method

Checks user capabilities and theme supports, and then saves the value of the setting.
Since: 3.4.0
final public save ( ) : false | void
return false | void False if cap check fails or value isn't set or is invalid.

set_root_value() protected method

Set the root value for a setting, especially for multidimensional ones.
Since: 4.4.0
protected set_root_value ( mixed $value ) : boolean
$value mixed Value to set as root of multidimensional setting.
return boolean Whether the multidimensional root was updated successfully.

update() protected method

Save the value of the setting, using the related API.
Since: 3.4.0
protected update ( mixed $value ) : boolean
$value mixed The value to update.
return boolean The result of saving the value.

validate() public method

Validates an input.
See also: WP_REST_Request::has_valid_params()
Since: 4.6.0
public validate ( mixed $value ) : true | WP_Error
$value mixed Value to validate.
return true | WP_Error True if the input was validated, otherwise WP_Error.

value() public method

Fetch the value of the setting.
Since: 3.4.0
public value ( ) : mixed
return mixed The value.

Property Details

$_original_value protected_oe property

Original non-previewed value stored by the preview method.
See also: WP_Customize_Setting::preview()
Since: 4.1.1
protected mixed $_original_value
return mixed

$_previewed_blog_id protected_oe property

The ID for the current site when the preview() method was called.
Since: 4.2.0
protected int $_previewed_blog_id
return integer

$aggregated_multidimensionals protected_oe static_oe property

Cache of multidimensional values to improve performance.
Since: 4.4.0
protected static array $aggregated_multidimensionals
return array

$capability public_oe property

Capability required to edit this setting.
public string $capability
return string

$default public_oe property

public $default

$dirty public_oe property

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.
Since: 4.2.0
public bool $dirty
return boolean

$id public_oe property

Unique string identifier for the setting.
public string $id
return string

$id_data protected_oe property

protected array $id_data
return array

$is_multidimensional_aggregated protected_oe property

Whether the multidimensional setting is aggregated.
Since: 4.4.0
protected bool $is_multidimensional_aggregated
return boolean

$is_previewed protected_oe property

Whether or not preview() was called.
Since: 4.4.0
protected bool $is_previewed
return boolean

$manager public_oe property

public WP_Customize_Manager $manager
return WP_Customize_Manager

$sanitize_callback public_oe property

public $sanitize_callback

$sanitize_js_callback public_oe property

public $sanitize_js_callback

$theme_supports public_oe property

Feature a theme is required to support to enable this setting.
public string $theme_supports
return string

$transport public_oe property

public $transport

$type public_oe property

public string $type
return string

$validate_callback public_oe property

Server-side sanitization callback for the setting's value.
public callback $validate_callback
return callback