Customize: Add setting validation model and control notifications to augment setting sanitization.

When a setting is invalid, not only will it be blocked from being saved but all other settings will be blocked as well. This ensures that Customizer saves aren't partial but are more transactional. User will be displayed the error in a notification so that they can fix and re-attempt saving.

PHP changes:

* Introduces `WP_Customize_Setting::validate()`, `WP_Customize_Setting::$validate_callback`, and the `customize_validate_{$setting_id}` filter.
* Introduces `WP_Customize_Manager::validate_setting_values()` to do validation (and sanitization) for the setting values supplied, returning a list of `WP_Error` instances for invalid settings.
* Attempting to save settings that are invalid will result in the save being blocked entirely, with the errors being sent in the `customize_save_response`. Modifies `WP_Customize_Manager::save()` to check all settings for validity issues prior to calling their `save` methods.
* Introduces `WP_Customize_Setting::json()` for parity with the other Customizer classes. This includes exporting of the `type`.
* Modifies `WP_Customize_Manager::post_value()` to apply `validate` after `sanitize`, and if validation fails, to return the `$default`.
* Introduces `customize_save_validation_before` action which fires right before the validation checks are made prior to saving.

JS changes:

* Introduces `wp.customize.Notification` in JS which to represent `WP_Error` instances returned from the server when setting validation fails.
* Introduces `wp.customize.Setting.prototype.notifications`.
* Introduces `wp.customize.Control.prototype.notifications`, which are synced with a control's settings' notifications.
* Introduces `wp.customize.Control.prototype.renderNotifications()` to re-render a control's notifications in its notification area. This is called automatically when the notifications collection changes.
* Introduces `wp.customize.settingConstructor`, allowing custom setting types to be used in the same way that custom controls, panels, and sections can be made.
* Injects a notification area into existing controls which is populated in response to the control's `notifications` collection changing. A custom control can customize the placement of the notification area by overriding the new `getNotificationsContainerElement` method.
* When a save fails due to setting invalidity, the invalidity errors will be added to the settings to then populate in the controls' notification areas, and the first such invalid control will be focused.

Props westonruter, celloexpressions, mrahmadawais.
See #35210.
See #30937.
Fixes #34893.


git-svn-id: https://develop.svn.wordpress.org/trunk@37476 602fd350-edb4-49c9-b593-d223f7449a82

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

@@ -59,6 +59,7 @@ class WP_Customize_Setting {
 	 *
 	 * @var callback
 	 */
+	public $validate_callback    = '';
 	public $sanitize_callback    = '';
 	public $sanitize_js_callback = '';
 
@@ -142,6 +143,9 @@ class WP_Customize_Setting {
 			$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 );
 		}
@@ -464,14 +468,16 @@ class WP_Customize_Setting {
 	 * the value of the setting.
 	 *
 	 * @since 3.4.0
+	 * @since 4.6.0 Return the result of updating the value.
 	 *
-	 * @return false|void False if cap check fails or value isn't set.
+	 * @return false|void False if cap check fails or value isn't set or is invalid.
 	 */
 	final public function save() {
 		$value = $this->post_value();
 
-		if ( ! $this->check_capabilities() || ! isset( $value ) )
+		if ( ! $this->check_capabilities() || ! isset( $value ) ) {
 			return false;
+		}
 
 		/**
 		 * Fires when the WP_Customize_Setting::save() method is called.
@@ -483,7 +489,7 @@ class WP_Customize_Setting {
 		 *
 		 * @param WP_Customize_Setting $this WP_Customize_Setting instance.
 		 */
-		do_action( 'customize_save_' . $this->id_data[ 'base' ], $this );
+		do_action( 'customize_save_' . $this->id_data['base'], $this );
 
 		$this->update( $value );
 	}
@@ -494,7 +500,7 @@ class WP_Customize_Setting {
 	 * @since 3.4.0
 	 *
 	 * @param mixed $default A default value which is used as a fallback. Default is null.
-	 * @return mixed The default value on failure, otherwise the sanitized value.
+	 * @return mixed The default value on failure, otherwise the sanitized and validated value.
 	 */
 	final public function post_value( $default = null ) {
 		return $this->manager->post_value( $this, $default );
@@ -505,8 +511,8 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string|array $value The value to sanitize.
-	 * @return string|array|null Null if an input isn't valid, otherwise the sanitized value.
+	 * @param string|array $value    The value to sanitize.
+	 * @return string|array|null|WP_Error Sanitized value, or `null`/`WP_Error` if invalid.
 	 */
 	public function sanitize( $value ) {
 
@@ -521,6 +527,45 @@ class WP_Customize_Setting {
 		return apply_filters( "customize_sanitize_{$this->id}", $value, $this );
 	}
 
+	/**
+	 * Validate an input.
+	 *
+	 * @since 4.6.0
+	 * @access public
+	 * @see WP_REST_Request::has_valid_params()
+	 *
+	 * @param mixed $value Value to validate.
+	 * @return true|WP_Error
+	 */
+	public function validate( $value ) {
+		if ( is_wp_error( $value ) ) {
+			return $value;
+		}
+		if ( is_null( $value ) ) {
+			return new WP_Error( 'invalid_value', __( 'Invalid value.' ) );
+		}
+
+		$validity = new WP_Error();
+
+		/**
+		 * Validate a Customize setting value.
+		 *
+		 * Plugins should amend the `$validity` object via its `WP_Error::add()` method.
+		 *
+		 * @since 4.6.0
+		 *
+		 * @param WP_Error             $validity Filtered from `true` to `WP_Error` when invalid.
+		 * @param mixed                $value    Value of the setting.
+		 * @param WP_Customize_Setting $this     WP_Customize_Setting instance.
+		 */
+		$validity = apply_filters( "customize_validate_{$this->id}", $validity, $value, $this );
+
+		if ( is_wp_error( $validity ) && empty( $validity->errors ) ) {
+			$validity = true;
+		}
+		return $validity;
+	}
+
 	/**
 	 * Get the root value for a setting, especially for multidimensional ones.
 	 *
@@ -699,6 +744,22 @@ class WP_Customize_Setting {
 		return $value;
 	}
 
+	/**
+	 * Get the data to export to the client via JSON.
+	 *
+	 * @since 4.6.0
+	 *
+	 * @return array Array of parameters passed to JavaScript.
+	 */
+	public function json() {
+		return array(
+			'value'     => $this->js_value(),
+			'transport' => $this->transport,
+			'dirty'     => $this->dirty,
+			'type'      => $this->type,
+		);
+	}
+
 	/**
 	 * Validate user capabilities whether the theme supports the setting.
 	 *