<?php

/**

 * WordPress Customize Setting classes

 *

 * @package WordPress

 * @subpackage Customize

 * @since 3.4.0

 */

/**

 * Customize Setting class.

 *

 * Handles saving and sanitizing of settings.

 *

 * @since 3.4.0

 *

 * @see WP_Customize_Manager

 * @link https://developer.wordpress.org/themes/customize-api

 */

#[AllowDynamicProperties]

class WP_Customize_Setting {

	/**

	 * Customizer bootstrap instance.

	 *

	 * @since 3.4.0

	 * @var WP_Customize_Manager

	 */

	public $manager;

	/**

	 * Unique string identifier for the setting.

	 *

	 * @since 3.4.0

	 * @var string

	 */

	public $id;

	/**

	 * Type of customize settings.

	 *

	 * @since 3.4.0

	 * @var string

	 */

	public $type = 'theme_mod';

	/**

	 * Capability required to edit this setting.

	 *

	 * @since 3.4.0

	 * @var string|array

	 */

	public $capability = 'edit_theme_options';

	/**

	 * Theme features required to support the setting.

	 *

	 * @since 3.4.0

	 * @var string|string[]

	 */

	public $theme_supports = '';

	/**

	 * The default value for the setting.

	 *

	 * @since 3.4.0

	 * @var string

	 */

	public $default = '';

	/**

	 * Options for rendering the live preview of changes in 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.

	 *

	 * @since 3.4.0

	 * @var string

	 */

	public $transport = 'refresh';

	/**

	 * Server-side validation callback for the setting's value.

	 *

	 * @since 4.6.0

	 * @var callable

	 */

	public $validate_callback = '';

	/**

	 * Callback to filter a Customize setting value in un-slashed form.

	 *

	 * @since 3.4.0

	 * @var callable

	 */

	public $sanitize_callback = '';

	/**

	 * Callback to convert a Customize PHP setting value to a value that is JSON serializable.

	 *

	 * @since 3.4.0

	 * @var callable

	 */

	public $sanitize_js_callback = '';

	/**

	 * 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.

	 *

	 * @since 4.2.0

	 * @var bool

	 */

	public $dirty = false;

	/**

	 * ID Data.

	 *

	 * @since 3.4.0

	 * @var array

	 */

	protected $id_data = array();

	/**

	 * Whether or not preview() was called.

	 *

	 * @since 4.4.0

	 * @var bool

	 */

	protected $is_previewed = false;

	/**

	 * Cache of multidimensional values to improve performance.

	 *

	 * @since 4.4.0

	 * @var array

	 */

	protected static $aggregated_multidimensionals = array();

	/**

	 * Whether the multidimensional setting is aggregated.

	 *

	 * @since 4.4.0

	 * @var bool

	 */

	protected $is_multidimensional_aggregated = false;

	/**

	 * Constructor.

	 *

	 * Any supplied $args override class property defaults.

	 *

	 * @since 3.4.0

	 *

	 * @param WP_Customize_Manager $manager Customizer bootstrap instance.

	 * @param string               $id      A specific ID of the setting.

	 *                                      Can be a theme mod or option name.

	 * @param array                $args    {

	 *     Optional. Array of properties for the new Setting object. Default empty array.

	 *

	 *     @type string          $type                 Type of the setting. Default 'theme_mod'.

	 *     @type string          $capability           Capability required for the setting. Default 'edit_theme_options'

	 *     @type string|string[] $theme_supports       Theme features required to support the panel. Default is none.

	 *     @type string          $default              Default value for the setting. Default is empty string.

	 *     @type string          $transport            Options for rendering the live preview of changes in Customizer.

	 *                                                 Using 'refresh' makes the change visible by reloading the whole preview.

	 *                                                 Using 'postMessage' allows a custom JavaScript to handle live changes.

	 *                                                 Default is 'refresh'.

	 *     @type callable        $validate_callback    Server-side validation callback for the setting's value.

	 *     @type callable        $sanitize_callback    Callback to filter a Customize setting value in un-slashed form.

	 *     @type callable        $sanitize_js_callback Callback to convert a Customize PHP setting value to a value that is

	 *                                                 JSON serializable.

	 *     @type bool            $dirty                Whether or not the setting is initially dirty when created.

	 * }

	 */

	public function __construct( $manager, $id, $args = array() ) {

		$keys = array_keys( get_object_vars( $this ) );

		foreach ( $keys as $key ) {

			if ( isset( $args[ $key ] ) ) {

				$this->$key = $args[ $key ];

			}

		}

		$this->manager = $manager;

		$this->id      = $id;

		// Parse the ID for array keys.

		$this->id_data['keys'] = preg_split( '/\[/', str_replace( ']', '', $this->id ) );

		$this->id_data['base'] = array_shift( $this->id_data['keys'] );

		// Rebuild the ID.

		$this->id = $this->id_data['base'];

		if ( ! empty( $this->id_data['keys'] ) ) {

			$this->id .= '[' . implode( '][', $this->id_data['keys'] ) . ']';

		}

		if ( $this->validate_callback ) {

			add_filter( "customize_validate_{$this->id}", $this->validate_callback, 10, 3 );

		}

		if ( $this->sanitize_callback ) {

			add_filter( "customize_sanitize_{$this->id}", $this->sanitize_callback, 10, 2 );

		}

		if ( $this->sanitize_js_callback ) {

			add_filter( "customize_sanitize_js_{$this->id}", $this->sanitize_js_callback, 10, 2 );

		}

		if ( 'option' === $this->type || 'theme_mod' === $this->type ) {

			// Other setting types can opt-in to aggregate multidimensional explicitly.

			$this->aggregate_multidimensional();

			// Allow option settings to indicate whether they should be autoloaded.

			if ( 'option' === $this->type && isset( $args['autoload'] ) ) {

				self::$aggregated_multidimensionals[ $this->type ][ $this->id_data['base'] ]['autoload'] = $args['autoload'];

			}

		}

	}

	/**

	 * Get parsed ID data for multidimensional setting.

	 *

	 * @since 4.4.0

	 *

	 * @return array {

	 *     ID data for multidimensional setting.

	 *

	 *     @type string $base ID base

	 *     @type array  $keys Keys for multidimensional array.

	 * }

	 */

	final public function id_data() {

		return $this->id_data;

	}

	/**

	 * Set up the setting for aggregated multidimensional values.

	 *

	 * 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

	 */

	protected function aggregate_multidimensional() {

		$id_base = $this->id_data['base'];

		if ( ! isset( self::$aggregated_multidimensionals[ $this->type ] ) ) {

			self::$aggregated_multidimensionals[ $this->type ] = array();

		}

		if ( ! isset( self::$aggregated_multidimensionals[ $this->type ][ $id_base ] ) ) {

			self::$aggregated_multidimensionals[ $this->type ][ $id_base ] = array(

				'previewed_instances'       => array(), // Calling preview() will add the $setting to the array.

				'preview_applied_instances' => array(), // Flags for which settings have had their values applied.

				'root_value'                => $this->get_root_value( array() ), // Root value for initial state, manipulated by preview and update calls.

			);

		}

		if ( ! empty( $this->id_data['keys'] ) ) {

			// Note the preview-applied flag is cleared at priority 9 to ensure it is cleared before a deferred-preview runs.

			add_action( "customize_post_value_set_{$this->id}", array( $this, '_clear_aggregated_multidimensional_preview_applied_flag' ), 9 );

			$this->is_multidimensional_aggregated = true;

		}

	}

	/**

	 * Reset `$aggregated_multidimensionals` static variable.

	 *

	 * This is intended only for use by unit tests.

	 *

	 * @since 4.5.0

	 * @ignore

	 */

	public static function reset_aggregated_multidimensionals() {

		self::$aggregated_multidimensionals = array();

	}

	/**

	 * The ID for the current site when the preview() method was called.

	 *

	 * @since 4.2.0

	 * @var int

	 */

	protected $_previewed_blog_id;

	/**

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

	 *

	 * @since 4.2.0

	 *

	 * @return bool If preview() has been called.

	 */

	public function is_current_blog_previewed() {

		if ( ! isset( $this->_previewed_blog_id ) ) {

			return false;

		}

		return ( get_current_blog_id() === $this->_previewed_blog_id );

	}

	/**

	 * Original non-previewed value stored by the preview method.

	 *

	 * @see WP_Customize_Setting::preview()

	 * @since 4.1.1

	 * @var mixed

	 */

	protected $_original_value;

	/**

	 * Add filters to supply the setting's value when accessed.

	 *

	 * 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.

	 *

	 * @return bool False when preview short-circuits due no change needing to be previewed.

	 */

	public function preview() {

		if ( ! isset( $this->_previewed_blog_id ) ) {

			$this->_previewed_blog_id = get_current_blog_id();

		}

		// Prevent re-previewing an already-previewed setting.

		if ( $this->is_previewed ) {

			return true;

		}

		$id_base                 = $this->id_data['base'];

		$is_multidimensional     = ! empty( $this->id_data['keys'] );

		$multidimensional_filter = array( $this, '_multidimensional_preview_filter' );

		/*

		 * Check if the setting has a pre-existing value (an isset check),

		 * and if doesn't have any incoming post value. If both checks are true,

		 * then the preview short-circuits because there is nothing that needs

		 * to be previewed.

		 */

		$undefined     = new stdClass();

		$needs_preview = ( $undefined !== $this->post_value( $undefined ) );

		$value         = null;

		// Since no post value was defined, check if we have an initial value set.

		if ( ! $needs_preview ) {

			if ( $this->is_multidimensional_aggregated ) {

				$root  = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value'];

				$value = $this->multidimensional_get( $root, $this->id_data['keys'], $undefined );

			} else {

				$default       = $this->default;

				$this->default = $undefined; // Temporarily set default to undefined so we can detect if existing value is set.

				$value         = $this->value();

				$this->default = $default;

			}

			$needs_preview = ( $undefined === $value ); // Because the default needs to be supplied.

		}

		// If the setting does not need previewing now, defer to when it has a value to preview.

		if ( ! $needs_preview ) {

			if ( ! has_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) ) ) {

				add_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) );

			}

			return false;

		}

		switch ( $this->type ) {

			case 'theme_mod':

				if ( ! $is_multidimensional ) {

					add_filter( "theme_mod_{$id_base}", array( $this, '_preview_filter' ) );

				} else {

					if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) {

						// Only add this filter once for this ID base.

						add_filter( "theme_mod_{$id_base}", $multidimensional_filter );

					}

					self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this;

				}

				break;

			case 'option':

				if ( ! $is_multidimensional ) {

					add_filter( "pre_option_{$id_base}", array( $this, '_preview_filter' ) );

				} else {

					if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) {

						// Only add these filters once for this ID base.

						add_filter( "option_{$id_base}", $multidimensional_filter );

						add_filter( "default_option_{$id_base}", $multidimensional_filter );

					}

					self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this;

				}

				break;

			default:

				/**

				 * Fires when the WP_Customize_Setting::preview() method is called for settings

				 * not handled as theme_mods or options.

				 *

				 * The dynamic portion of the hook name, `$this->id`, refers to the setting ID.

				 *

				 * @since 3.4.0

				 *

				 * @param WP_Customize_Setting $setting WP_Customize_Setting instance.

				 */

				do_action( "customize_preview_{$this->id}", $this );

				/**

				 * Fires when the WP_Customize_Setting::preview() method is called for settings

				 * not handled as theme_mods or options.

				 *

				 * The dynamic portion of the hook name, `$this->type`, refers to the setting type.

				 *

				 * @since 4.1.0

				 *

				 * @param WP_Customize_Setting $setting WP_Customize_Setting instance.