id	summary	reporter	owner	description	type	status	priority	milestone	component	version	severity	resolution	keywords	cc
12254	Move show_message() into WP_Error class and add support for various WP_Error features that are missing	jeremyclarke	jeremyclarke	"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?"	enhancement	new	normal	Future Release	General		normal			jeremyclarke WordPress@… mikeschinkel@… Ryan_B johnbillion@… simon@…