W3cubDocs

/WordPress

WP_Error

WordPress Error class.

Description

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.

More Information

WP_Error is a class that makes error handling within plugins and WordPress itself much easier.

Instances of WP_Error store error codes and messages representing one or more errors, and whether or not a variable is an instance of WP_Error can be determined using the is_wp_error() function.

Error Codes

Error codes are slugs that are used to identify each error. They are mostly useful when a piece of code can produce several different errors, and you want to handle each of those errors differently.

The error codes used in WordPress are not integers, but strings, with any spaces between words replaced with underscores (example: an_error_code). The error codes used in WordPress are usually based on the error message associated with that code.

Methods and Properties

Please refer source code for the complete lists of methods and properties. Below description may cover some of them.

Properties

$errors
Array containing the list of errors.
$error_data
Array containing the list of data for error codes.

Methods

__construct( $code = '', $message = '', $data = '' )
Sets up the error message. All parameters are optional, and if the $code parameter is empty, the other parameters will be ignored. When you pass a value for the $code parameter, the $message will be added for that code, even if you did not pass a value for $message (but $data will be used only when you pass a value for $data). It is possible to add multiple messages to the same code by using other methods in the class.
get_error_codes()
Retrieve all error codes. Access public, returns array List of error codes, if available.
get_error_code()
Retrieve first error code available. Access public, returns string, int or Empty if there is no error codes
get_error_messages($code)
Retrieve all error messages or error messages matching code. Access public, returns an array of error strings on success, or empty array on failure (if using code parameter)
get_error_message($code)
Get 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. Returns an error string.
get_error_data($code)
Retrieve error data for error code. Returns mixed or null, if no errors.
add($code, $message, $data)
Append more error messages to list of error messages. No return.
add_data($data, $code)
Add data for error code. The error code can only contain one error data. No return.
remove($code)
Remove any messages and data associated with an error code. No return.
  • see is_wp_error() for more information on trapping for errors (particularly useful when faced with the dreaded ‘Catchable fatal error: Object of class WP_Error could not be converted to string’)

Source

File: wp-includes/class-wp-error.php

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

	/**
	 * Stores the list of data for error codes.
	 *
	 * @since 2.1.0
	 * @var array
	 */
	public $error_data = array();

	/**
	 * Initialize 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.
	 */
	public function __construct( $code = '', $message = '', $data = '' ) {
		if ( empty( $code ) ) {
			return;
		}

		$this->errors[ $code ][] = $message;

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

	/**
	 * Retrieve 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 );
	}

	/**
	 * Retrieve 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];
	}

	/**
	 * Retrieve all error messages or error messages matching code.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Optional. Retrieve messages matching code, if exists.
	 * @return array Error strings on success, or empty array on failure (if using code parameter).
	 */
	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();
		}
	}

	/**
	 * Get 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 message.
	 * @return string
	 */
	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];
	}

	/**
	 * Retrieve error data for error code.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Optional. Error code.
	 * @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 ];
		}
	}

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

	/**
	 * Add an error or append 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.
	 */
	public function add( $code, $message, $data = '' ) {
		$this->errors[ $code ][] = $message;
		if ( ! empty( $data ) ) {
			$this->error_data[ $code ] = $data;
		}
	}

	/**
	 * Add data for error code.
	 *
	 * The error code can only contain one error data.
	 *
	 * @since 2.1.0
	 *
	 * @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();
		}

		$this->error_data[ $code ] = $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 ] );
	}
}

Methods

  • __construct — Initialize the error.
  • __get — Make private properties readable for backwards compatibility.
  • __isset — Make private properties checkable for backwards compatibility.
  • __set — Make private properties settable for backwards compatibility.
  • __unset — Make private properties un-settable for backwards compatibility.
  • add — Add an error or append additional message to an existing error.
  • add_data — Add data for error code.
  • get_error_code — Retrieve first error code available.
  • get_error_codes — Retrieve all error codes.
  • get_error_data — Retrieve error data for error code.
  • get_error_message — Get single error message.
  • get_error_messages — Retrieve all error messages or error messages matching code.
  • has_errors — Verify if the instance contains errors.
  • remove — Removes the specified error.

Changelog

Version Description
2.1.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/classes/wp_error