WordPress has a class called WP_Error that provides a really simple way for developers to track errors while processing data. The class mystified me for a long time, but once I figured it out, it is extremely simple to use, and saves a ton of time when attempting to record errors while processing data of any kind. This video is just a quick introduction to the WP_Error class that will show you the very basics of how to use it.

Note: It’s been brought to my attention that the audio level is extremely low in this video. I’m not sure what happened. Sorry.

As noted in the video, I highly recommend that you read through the Codex page on WP_Error and that take a look at the class in the WordPress source.

// sets up the sample short code
function pw_form_shortcode( $atts, $content = null ) {
	ob_start(); ?>
		<form id="pw_sample_error_form" method="post">
			<input type="text" name="pw_numbers" value="" />
			<?php wp_nonce_field( 'pw_error_nonce', 'pw_error_nonce_action' ); ?>
			<input type="submit" name="pw_process_numbers" value="<?php _e('Submit'); ?>"/>
	return apply_filters( 'pw_form_shortcode', ob_get_clean() ); 
add_shortcode( 'pw_error_demo', 'pw_form_shortcode' );
// processes our short code
function pw_process_form_submission() {
	if( isset( $_POST['pw_process_numbers'] ) && wp_verify_nonce( $_POST['pw_error_nonce_action'], 'pw_error_nonce' ) ) {
		$numbers = is_numeric( $_POST['pw_numbers'] ) 
			? stripslashes( $_POST['pw_numbers'] ) 
			: new WP_Error('numbers_only', __('Please only enter numbers', 'pippin' ) );
		if( is_wp_error( $numbers ) )
			wp_die( $numbers->get_error_message(), __('Input Error', 'pippin') );
		// input verified to be numeric, now do something with it
add_action( 'init', 'pw_process_form_submission' );
  1. Jean

    Excellent video Pippin, glad you tackled this class.

    Two questions:

    You showed its usage very clearly, now I’d like to know what advantages there are in using the WP_Error class versus doing your validation the normal way, for example with if statements. For sure its always better to use native WordPress functions than custom PHP where possible, and I can see that storing the errors in variables can be useful as well, apart from the ready made error display interface. Are there any other advantages? Should we always use this class when building plugins, or are there any cases where a simple if statement would be more practical?

    I also noticed that you have that ob_start() function call right at the top, is that for caching, and when should we be using that?


    • Pippin

      I think the main reason to use this is just that there isn’t often a reason not to. This class is included in core and works perfectly, so why not use it? I can, however, tell you at least one instance where I chose to not use it, and that was because it wouldn’t work for me. In Easy Digital Downloads, I created my own error tracking system for logging errors during checkout. WP_Error didn’t work here because I needed the errors to be available even after page reload, which is not the case (by default) with WP_Error.

      The ob_start() is only for the short code. The contents of a short code must always be returned, so the output buffer simply gives me a way to drop all of the HTML into a variable.

    • Jean

      Got that Pippin, thanks!

  2. Mark Simchock

    Hi Pippin

    Thanks for this head start. I think it helps. i’ll know shortly if this class is a good match for my needs.

    In a previous comment you said, “WP_Error didn’t work here because I needed the errors to be available even after page reload, which is not the case (by default) with WP_Error.”

    Can you zoom in on this a bit? That is, provide some detail.

    You example was helpful but it’s also super basic. Exit / die on error isn’t what I’m looking for. i want to submit a form (e.g., meta box with custom fields for a custom post type), validate that, and then if necessary display any / all errors.

    I’m gonna go dive in now. But perhaps you’ll reply to this in time to help. i hope so 🙂

    Thanks again

  3. Henry Wright

    I notice you used die() in the example. This refreshes the page and the text the user has entered into the field is lost. How could you display the error message on the same page as the form and not lose the text the user has input into the text field?

    • Pippin

      You will set the errors, do not die(), and then just let the page reload (put the error display inside the page template).

      In order to keep the field data, you should check if the $_POST[‘key’] is set for each field and then set the field values to the post value if it is.

    • Henry Wright

      Thanks, I’ll give that a shot.

Comments are closed.