[wp-trac] [WordPress Trac] #34893: Improve Customizer setting validation model

[WordPress Trac]

#34893: Improve Customizer setting validation model
-------------------------------------+--------------------------
 Reporter:  westonruter              |       Owner:  westonruter
     Type:  enhancement              |      Status:  accepted
 Priority:  normal                   |   Milestone:  4.5
Component:  Customize                |     Version:  3.4
 Severity:  normal                   |  Resolution:
 Keywords:  has-patch needs-testing  |     Focuses:  javascript
-------------------------------------+--------------------------
Description changed by westonruter:

Old description:

> Customizer setting values need to be able to be validated and for any
> validation errors to block the Customizer from saving any setting until
> all are valid.
>
> Settings in the Customizer rely on sanitization to ensure that only valid
> values get persisted to the database. The sanitization in the Customizer
> generally allows values to be passed through to be persisted and does not
> enforce validation that blocks the saving of the value. This is in large
> part because there is no standard facility for showing error messages
> relating to Customizer controls, and there is no standard method to raise
> validation errors. A Customizer setting ''can'' be blocked from being
> saved by returning `null` from the `WP_Customize_Setting::sanitize()`
> method (i.e. generally returned via `customize_sanitize_{$setting_id}`).
> When this is done, however, the modified value completely disappears from
> the preview with no indication for why the value seems to be reset to the
> default.
>
> In JavaScript there is the `wp.customize.Setting.prototype.validate()`
> method that can be extended to return `null` in the case where the value
> should be rejected, but again this does not provide a way to display a
> validation message: the user can be entering data but they just stop
> seeing the value making changes in the preview without any feedback. Even
> worse, if the JS `validate` method actually manipulates the value to make
> it valid, there can be strange behavior in the UI as the user provides
> input, likely having to do with the two-way data binding of
> `wp.customize.Element` instances.
>
> Furthermore, if one setting is blocked from being saved by means of
> validation in the sanitization method, the other settings in the
> Customizer state may very well be completely valid, and thus they would
> save successfully. The result is that some settings would get saved,
> whereas others would not, and the user wouldn't know which were
> successful and which failed (again, since there is no standard mechanism
> for showing validation error message). The Customizer state would only
> partially get persisted to the database. This isn't good.
>
> We need to improve the Customizer by:
>
> * Validating settings on server before save.
> * Displaying validation error messages from server and from JS client.
> * Performing transactional/atomic setting saving, rejecting all settings
> if one is invalid.
>
> Since the `WP_Customize_Setting::sanitize()` already partially supports
> validation by returning `null`, we can build on that to also allow it to
> return a `WP_Error` object. We'd want to retain the regular fuzzy
> sanitization during preview updates, but during the `customize_save`
> action we'd want to impose a strict pass/fail for setting validation.
>
> This is closely related and complimentary to #30937: Add Customizer
> transactions
>
> For the notification bar to display validation error messages, see
> #35210.

New description:

 Customizer setting values need to be able to be validated and for any
 validation errors to block the Customizer from saving any setting until
 all are valid.

 Settings in the Customizer rely on sanitization to ensure that only valid
 values get persisted to the database. The sanitization in the Customizer
 generally allows values to be passed through to be persisted and does not
 enforce validation that blocks the saving of the value. This is in large
 part because there is no standard facility for showing error messages
 relating to Customizer controls, and there is no standard method to raise
 validation errors. A Customizer setting ''can'' be blocked from being
 saved by returning `null` from the `WP_Customize_Setting::sanitize()`
 method (i.e. generally returned via `customize_sanitize_{$setting_id}`).
 When this is done, however, the modified value completely disappears from
 the preview with no indication for why the value seems to be reset to the
 default.

 In JavaScript there is the `wp.customize.Setting.prototype.validate()`
 method that can be extended to return `null` in the case where the value
 should be rejected, but again this does not provide a way to display a
 validation message: the user can be entering data but they just stop
 seeing the value making changes in the preview without any feedback. Even
 worse, if the JS `validate` method actually manipulates the value to make
 it valid, there can be strange behavior in the UI as the user provides
 input, likely having to do with the two-way data binding of
 `wp.customize.Element` instances.

 Furthermore, if one setting is blocked from being saved by means of
 validation in the sanitization method, the other settings in the
 Customizer state may very well be completely valid, and thus they would
 save successfully. The result is that some settings would get saved,
 whereas others would not, and the user wouldn't know which were successful
 and which failed (again, since there is no standard mechanism for showing
 validation error message). The Customizer state would only partially get
 persisted to the database. This isn't good.

 We need to improve the Customizer by:

 * Validating settings on server before save.
 * Displaying validation error messages from server and from JS client.
 * Performing transactional/atomic setting saving, rejecting all settings
 if one is invalid.

 Since the `WP_Customize_Setting::sanitize()` already partially supports
 validation by returning `null`, we can build on that to also allow it to
 return a `WP_Error` object. We'd want to retain the regular fuzzy
 sanitization during preview updates, but during the `customize_save`
 action we'd want to impose a strict pass/fail for setting validation.

 This is closely related and complimentary to #30937: Add Customizer
 transactions

 For the notification bar to display validation error messages, see #35210.

 Feature plugin: https://github.com/xwp/wp-customize-setting-validation

--

--
Ticket URL: <https://core.trac.wordpress.org/ticket/34893#comment:13>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform