[wp-trac] [WordPress Trac] #11474: Add validation error reporting system to Settings API

[WordPress Trac]

#11474: Add validation error reporting system to Settings API
----------------------------+-----------------------------------------------
 Reporter:  jeremyclarke    |       Owner:  jeremyclarke           
     Type:  enhancement     |      Status:  new                    
 Priority:  high            |   Milestone:  3.0                    
Component:  Administration  |     Version:  2.9                    
 Severity:  normal          |    Keywords:  has-patch needs-testing
----------------------------+-----------------------------------------------
Changes (by jeremyclarke):

  * keywords:  needs-patch => has-patch needs-testing


Comment:

 The patch above adds error reporting to the Settings API mostly as I
 described in the ticket and other comments. I've carefully documented all
 the functions I added so looking at the diff and files should mostly
 explain it. I also added documentation to many of the other Settings API
 functions so the system should be easier to pick up without a tutorial.

 == Testing the system ==

 To test this you need to have a settings page set up with
 add_settings_sections() and add_settings_field(). You can add calls to
 {{{add_settings_error()}}} inside your setting's validation callback
 function when you notice a problem with a setting. The resulting error
 messages should show up when the page reloads. If there were no errors it
 should show the same old Settings Saved message.

 The output errors have the same format as the old Settings Saved message:
 div->p->strong, The div has a custom ID and several classes for CSS. It is
 set up to take advantage of the 'error' and 'updated' CSS classes from the
 admin, which is why the two $type's for errors are error and updated.
 Error will be red and updated will be yellow.

 The other use-case for this is to add settings errors inside your
 validator that check the data even when its not being saved. Things like
 checking for a missing option and complaining until it gets set. If you
 use settings_errors() yourself inside your setting page function you can
 make it show these errors with its $sanitize function, which will re-
 sanitize the setting without saving it then show you any errors that
 resulted. Using the $hide_on_update setting is a good idea if you do this,
 as it will stop the manual error display from showing if they are already
 showing in the default post-submission process.



 == New globals and storage ==
  * '''$wp_settings_errors''' - Global storage array to hold errors logged
 during the current pageview
  * '''set_transient('settings_errors')''' transient storage array used to
 pass errors back from processing on options.php

 == '''wp-admin/includes/template.php''' ==
 Add new API functions and update docs
  * Register a settings error to be displayed to the user
 {{{
 add_settings_error( $setting, $id, $message, $type = 'error' )
 }}}
  * Fetch settings errors registered by add_settings_error()
 {{{
 get_settings_errors( $setting = '', $sanitize = FALSE )
 }}}
  * Display settings errors registered by add_settings_error()
 {{{
 settings_errors($setting = '', $sanitize = FALSE, $hide_on_update = FALSE
 )
 }}}


 == '''wp-admin/options-head.php''' ==
  * Show settings errors in options-head.php so it always runs on settings
 pages.

 Previously there was a generic 'Settings saved' message that would show
 anytime $_GET[ 'updated' ], even if the saved settings had been validated
 out of existence. Now a call to settings_errors() is there, so that any
 errors registered so far that pageload or on the previous pageload get
 shown. The generic message is now registered as a settings error using the
 API in wp-admin/options.php

 == '''wp-admin/options.php''' ==
  * Use settings errors to return back to settings pages instead of just
 returning 'updated'.

 This file has the place where the user's settings page submission is
 forwarded back to the page they started on. It needed to be modified to
 save any settings registered during the setting processing (using its
 $sanitize_callback function as defined in register_setting()) ) into a
 transient before forwarding back. The patch also adds the 'settings saved'
 message to the registered errors before saving them, so that the generic
 updated message will automatically be shown when settings_errors() is
 called on the settings page.

 == '''wp-includes/formatting.php''' ==
  * Use settings errors during the validation of the admin_email option
 hard-coded in sanitize_option()

 This is an example of how the system is used as well as a fix for a
 particularly big hole in how settings saving currently works. Without this
 patch users are able to enter an empty or even just malformed (no @ sign
 etc.) admin email value and effectively erase all signs of an admin email,
 '''without even being shown an error to indicate that they have erased the
 admin email which is a bad idea'''.

 Once the system is set in place it will be goood to consider what other
 core settings might need better error messaging about innapropriate
 values.

 == WP_ERROR ==
 Anyone have an opinion about this? The current patch doesn't use WP_Error
 class. Should it? Anyone have an idea for how it should be used?

 == Still TO DO ==
 These are things i know still need doing. Please let me know if you think
 something else is missing. I will make a follow up patch that includes
 them and responds to any feedback.

  * add a filter to get_settings_errors()
  * add an action to settings_errors()

 Hopefully this can get in before the feature freeze. I will probably be
 able update it more based on any requests.

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/11474#comment:8>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software