[wp-trac] [WordPress Trac] #12254: Move show_message() into WP_Error class and add support for various WP_Error features that are missing

[WordPress Trac]

#12254: Move show_message() into WP_Error class and add support for various
WP_Error features that are missing
--------------------------+-------------------------------------------------
 Reporter:  jeremyclarke  |       Owner:  jeremyclarke
     Type:  enhancement   |      Status:  new         
 Priority:  normal        |   Milestone:  3.0         
Component:  General       |     Version:              
 Severity:  normal        |    Keywords:              
--------------------------+-------------------------------------------------
 Revisiting an old ticket about the mass upgrader (#11232) after working on
 my ticket for the Settings API (#11474) makes me think both cases are
 running into a wider problem related to the way WP_Error messages are
 handled system-wide. There just isn't a way to show them that fits with
 the detailed system that exists around logging errors with WP_Error. In
 both cases having a built-in way to display all messages logged in a
 WP_Error object would simplify their code and make their use of WP_Error
 much more logical and less haphazard.

 == WP_Error is intense ==
 WP_Error objects can have an infinite number of messages logged inside
 them into $code groups which themselves can even have multiple message
 values/

 {{{
  WP_Error::add($code, $message, $data = '')
 }}}

 You can then retrieve error messages for a specific code using
 WP_Error::get_error_messages()

 == show_message() is weak ==
 In contrast to this useful maleability is the show_message() function used
 by various updater scripts to access WP_Error messages:

 {{{
 /**
  * {@internal Missing Short Description}}
  *
  * @since unknown
  *
  * @param unknown_type $message
  */
 function show_message($message) {
         if( is_wp_error($message) ){
                 if( $message->get_error_data() )
                         $message = $message->get_error_message() . ': ' .
 $message->get_error_data();
                 else
                         $message = $message->get_error_message();
         }
         echo "<p>$message</p>\n";
 }
 }}}

 Living in misc.php, this is clearly not the most loved function in
 WordPress, but beyond its lack of documentation and arguments it also
 actually doesn't make sense when combined with the nature of WP_Error, and
 I'd argue that it should be a first-class citizen of the WP_Error API.

 === Deal with the input as WP_Error class by default ===
 For one thing its argument is named $message, which is a misnomer since it
 also supports complex WP_Error objects. I think it should be called $error
 and it should attempt to handle the error object in as much detail as
 possible. If this function is given a string instead of an error_object it
 should just show the text with the default formatting.

 === Move it into the class defintion ===
 The function logic should also be moved to be inside WP_Error as
 ::show_message() as well as maybe adding a ::show_messages() to
 differentiate between forcing the first message in the object and showing
 any relevant messages. The original function can be kept as a shell for
 the class method.

 === Support $code and $data better ===
 The updated function should allow $code values to be specified to show
 only messages related to a specific error $code (from WP_Error::add()) as
 well as some kind of option specifying whether the contents of the $data
 value for the results should be displayed.

 === Add support for 'types' of errors for display purposes ===
 To really have valuable visual cues linked with error display the system
 needs to be adapted to handle error types like 'error', 'updated' and
 something green like 'success'. Having this be part of hte API would
 increase the likelihood of people using the system because it will make it
 easier to quickly add visual errors to a plugin. IMHO the easiest way to
 achieve this would be to link 'types' with CSS classes expected to exist
 in wp-admin. 'updated' and 'error' classes already exist, yellow and red
 respectively, and can be a starting point. This way marking an error as
 'error' or 'updated' automatically controls the color it will be when
 show_messages() is run.

 This would probably require modifying the WP_Error::wp_error() and
 WP_Error::add() methods to accept a 4th argument, but would be a great
 step forward.

 === Use nice formatting ===
 I think the formatting should be the same as the 'settings updated'
 message from after you save a settings page. It is malleable and stands
 out in the admin:
 {{{
 <div class="updated fade"><p><strong> MESSAGE </strong></p></div>
 }}}


 == Lets make showing errors easy ==
 Even though these functionalities aren't needed for the current uses of
 show_message() in the upgrader process I think they will inform and
 improve those systems when the changes are taken into account. WP_Error is
 fairly powerful but not used enough because it is incomplete and awkward.
 Improving show_message() to fill this hole will mature the API and
 hopefully get plugin authors using it in more detail. It would definitely
 make integrating WP_Error into the Settings API much easier.

 == Thoughts on this before I make a patch? ==

 I'll try to work on this soon but am interested in feedback. Anyone had
 this idea before and ran into a wall? Something else you think should be
 included?

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/12254>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software