WP_Error{}WP 2.1.0AllowDynamicProperties

WordPress Error class.

Container for checking for WordPress errors and error messages. Return WP_Error and use is_wp_error() to check if this class is returned. Many core WordPress functions pass this class in the event of an error and if not handled properly will result in code errors.

Hooks from the class

Usage

$WP_Error = new WP_Error();
// use class methods

Methods

  1. public __construct( $code = '', $message = '', $data = '' )
  2. public add( $code, $message, $data = '' )
  3. public add_data( $data, $code = '' )
  4. protected static copy_errors( WP_Error $from, WP_Error $to )
  5. public export_to( WP_Error $error )
  6. public get_all_error_data( $code = '' )
  7. public get_error_code()
  8. public get_error_codes()
  9. public get_error_data( $code = '' )
  10. public get_error_message( $code = '' )
  11. public get_error_messages( $code = '' )
  12. public has_errors()
  13. public merge_from( WP_Error $error )
  14. public remove( $code )

Examples

0

#1 Calling as a function

$error = new WP_Error( 'error_key', 'Error message...', 404 );

if( is_wp_error( $error ) ){
	echo $error->get_error_code();    //> error_key
	echo $error->get_error_message(); //> Error message...
	echo $error->get_error_data();    //> 404
}

When the function returns an instance of WP_Error created in it, which is then checked by function is_wp_error(). For example, WordPress function wp_insert_post() works on this principle: in case of an error, it returns the WP_Error object, which contains information about the error(s). Briefly, this approach can be written as follows:

function some_stuff( $some = false ){

	// The $some variable must be specified
	if( ! $some )
		return new WP_Error( 'fallen', 'He fell down and can`t get up' );
	else
		return true;
}

// now call the function to return an error
$return = some_stuff();

// check the variable for an error
if( is_wp_error( $return ) ){
	// print the error message: 'He fell down and can't get up'
	echo $return->get_error_message();
}

In the third parameter $data you can pass any data. But if the error is related to the request, in WordPress it is customary to pass the status of the response code in this parameter. For example, see the code of function wp_handle_comment_submission()

0

#2 Working with an object

When we create a variable with an instance of the class WP_Error and then work with that variable.

For example, we are making a feedback form and need to handle errors. In this case, an instance of the WP_Error class will work well. Here is an example of creating an instance and adding errors to it and handling them later:

// Create an instance
global $form_error;
$form_error = new WP_Error;

// This function, can be in another file
function foo(){
	global $form_error;

	// some code ...

	// check the field
	if( empty( $email ) ){
		$form_error->add( 'no_email', 'Fill email' );
	}
	elseif( ! is_email( $email ) ){
		$form_error->add( 'invalid_email', 'Invalid email' );
	}

	// check if there is an error, stop the function
	if( $form_error->get_error_code() ){
		// let the function not continue because of an error
		return; 
	}

}
// Another file (not the one with foo()) - the file with the output
// error messages, if any.
// Check if there are errors and print all messages if any
if( $form_error->get_error_code() ){

	foreach( $form_error->get_error_messages() as $error ){
		echo '<div><strong>Error</strong>:'. $error .'</div>';
	}
}
0

#3 What does a class instance look like?

To understand what the object WP_Error is, I suggest you look at it when it is filled:

// create an instance and immediately add data - add() method
$error = new WP_Error( 'fallen', 'The bug fell down and can't get up.' );

// add more data to the object
$error->add( 'help', 'He's waiting for someone to help him.' );

/* Now $error contains:

WP_Error Object
(
	[errors] => Array
		(
			[fallen] => Array
				(
					[0] => The beetle has fallen and cannot get up.
				)

			[help] => Array
				(
					[0] => He is waiting for someone to help him.
				)

		)

	[error_data] => Array
		(
		)

)
*/

// Let's add more data and specify a third parameter
$error->add( 'frost', 'Frost has fallen on the branches of the spruce.', 'error' );
$error->add( 'white', 'The needles turned white overnight.', 'message' );

/* Now $error contains:

WP_Error Object
(
	[errors] => Array
		(
			[fallen] => Array
				(
					[0] => The beetle has fallen and cannot get up.
				)

			[help] => Array
				(
					[0] => He is waiting for someone to help him.
				)

			[frost] => Array
				(
					[0] => Frost has fallen on the branches of a fir tree.
				)

			[white] => Array
				(
					[0] => The needles turned white overnight.
				)

		)

	[error_data] => Array
		(
			[frost] => error
			[white] => message
		)

)
*/

$all_data = $error->get_all_error_data( 'white' );
/* $all_data contains:
Array
(
	[0] => message
)
*/

$data = $error->get_error_data( 'white' );
/* $data contains:
message
*/

Changelog

Since 2.1.0 Introduced.

WP_Error{} code WP 6.4.3

class WP_Error {
	/**
	 * Stores the list of errors.
	 *
	 * @since 2.1.0
	 * @var array
	 */
	public $errors = array();

	/**
	 * Stores the most recently added data for each error code.
	 *
	 * @since 2.1.0
	 * @var array
	 */
	public $error_data = array();

	/**
	 * Stores previously added data added for error codes, oldest-to-newest by code.
	 *
	 * @since 5.6.0
	 * @var array[]
	 */
	protected $additional_data = array();

	/**
	 * Initializes the error.
	 *
	 * If `$code` is empty, the other parameters will be ignored.
	 * When `$code` is not empty, `$message` will be used even if
	 * it is empty. The `$data` parameter will be used only if it
	 * is not empty.
	 *
	 * Though the class is constructed with a single error code and
	 * message, multiple codes can be added using the `add()` method.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code    Error code.
	 * @param string     $message Error message.
	 * @param mixed      $data    Optional. Error data. Default empty string.
	 */
	public function __construct( $code = '', $message = '', $data = '' ) {
		if ( empty( $code ) ) {
			return;
		}

		$this->add( $code, $message, $data );
	}

	/**
	 * Retrieves all error codes.
	 *
	 * @since 2.1.0
	 *
	 * @return array List of error codes, if available.
	 */
	public function get_error_codes() {
		if ( ! $this->has_errors() ) {
			return array();
		}

		return array_keys( $this->errors );
	}

	/**
	 * Retrieves the first error code available.
	 *
	 * @since 2.1.0
	 *
	 * @return string|int Empty string, if no error codes.
	 */
	public function get_error_code() {
		$codes = $this->get_error_codes();

		if ( empty( $codes ) ) {
			return '';
		}

		return $codes[0];
	}

	/**
	 * Retrieves all error messages, or the error messages for the given error code.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Optional. Error code to retrieve the messages for.
	 *                         Default empty string.
	 * @return string[] Error strings on success, or empty array if there are none.
	 */
	public function get_error_messages( $code = '' ) {
		// Return all messages if no code specified.
		if ( empty( $code ) ) {
			$all_messages = array();
			foreach ( (array) $this->errors as $code => $messages ) {
				$all_messages = array_merge( $all_messages, $messages );
			}

			return $all_messages;
		}

		if ( isset( $this->errors[ $code ] ) ) {
			return $this->errors[ $code ];
		} else {
			return array();
		}
	}

	/**
	 * Gets a single error message.
	 *
	 * This will get the first message available for the code. If no code is
	 * given then the first code available will be used.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Optional. Error code to retrieve the message for.
	 *                         Default empty string.
	 * @return string The error message.
	 */
	public function get_error_message( $code = '' ) {
		if ( empty( $code ) ) {
			$code = $this->get_error_code();
		}
		$messages = $this->get_error_messages( $code );
		if ( empty( $messages ) ) {
			return '';
		}
		return $messages[0];
	}

	/**
	 * Retrieves the most recently added error data for an error code.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Optional. Error code. Default empty string.
	 * @return mixed Error data, if it exists.
	 */
	public function get_error_data( $code = '' ) {
		if ( empty( $code ) ) {
			$code = $this->get_error_code();
		}

		if ( isset( $this->error_data[ $code ] ) ) {
			return $this->error_data[ $code ];
		}
	}

	/**
	 * Verifies if the instance contains errors.
	 *
	 * @since 5.1.0
	 *
	 * @return bool If the instance contains errors.
	 */
	public function has_errors() {
		if ( ! empty( $this->errors ) ) {
			return true;
		}
		return false;
	}

	/**
	 * Adds an error or appends an additional message to an existing error.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code    Error code.
	 * @param string     $message Error message.
	 * @param mixed      $data    Optional. Error data. Default empty string.
	 */
	public function add( $code, $message, $data = '' ) {
		$this->errors[ $code ][] = $message;

		if ( ! empty( $data ) ) {
			$this->add_data( $data, $code );
		}

		/**
		 * Fires when an error is added to a WP_Error object.
		 *
		 * @since 5.6.0
		 *
		 * @param string|int $code     Error code.
		 * @param string     $message  Error message.
		 * @param mixed      $data     Error data. Might be empty.
		 * @param WP_Error   $wp_error The WP_Error object.
		 */
		do_action( 'wp_error_added', $code, $message, $data, $this );
	}

	/**
	 * Adds data to an error with the given code.
	 *
	 * @since 2.1.0
	 * @since 5.6.0 Errors can now contain more than one item of error data. {@see WP_Error::$additional_data}.
	 *
	 * @param mixed      $data Error data.
	 * @param string|int $code Error code.
	 */
	public function add_data( $data, $code = '' ) {
		if ( empty( $code ) ) {
			$code = $this->get_error_code();
		}

		if ( isset( $this->error_data[ $code ] ) ) {
			$this->additional_data[ $code ][] = $this->error_data[ $code ];
		}

		$this->error_data[ $code ] = $data;
	}

	/**
	 * Retrieves all error data for an error code in the order in which the data was added.
	 *
	 * @since 5.6.0
	 *
	 * @param string|int $code Error code.
	 * @return mixed[] Array of error data, if it exists.
	 */
	public function get_all_error_data( $code = '' ) {
		if ( empty( $code ) ) {
			$code = $this->get_error_code();
		}

		$data = array();

		if ( isset( $this->additional_data[ $code ] ) ) {
			$data = $this->additional_data[ $code ];
		}

		if ( isset( $this->error_data[ $code ] ) ) {
			$data[] = $this->error_data[ $code ];
		}

		return $data;
	}

	/**
	 * Removes the specified error.
	 *
	 * This function removes all error messages associated with the specified
	 * error code, along with any error data for that code.
	 *
	 * @since 4.1.0
	 *
	 * @param string|int $code Error code.
	 */
	public function remove( $code ) {
		unset( $this->errors[ $code ] );
		unset( $this->error_data[ $code ] );
		unset( $this->additional_data[ $code ] );
	}

	/**
	 * Merges the errors in the given error object into this one.
	 *
	 * @since 5.6.0
	 *
	 * @param WP_Error $error Error object to merge.
	 */
	public function merge_from( WP_Error $error ) {
		static::copy_errors( $error, $this );
	}

	/**
	 * Exports the errors in this object into the given one.
	 *
	 * @since 5.6.0
	 *
	 * @param WP_Error $error Error object to export into.
	 */
	public function export_to( WP_Error $error ) {
		static::copy_errors( $this, $error );
	}

	/**
	 * Copies errors from one WP_Error instance to another.
	 *
	 * @since 5.6.0
	 *
	 * @param WP_Error $from The WP_Error to copy from.
	 * @param WP_Error $to   The WP_Error to copy to.
	 */
	protected static function copy_errors( WP_Error $from, WP_Error $to ) {
		foreach ( $from->get_error_codes() as $code ) {
			foreach ( $from->get_error_messages( $code ) as $error_message ) {
				$to->add( $code, $error_message );
			}

			foreach ( $from->get_all_error_data( $code ) as $data ) {
				$to->add_data( $data, $code );
			}
		}
	}
}