WordPress/wp-includes/class-wp-error.php
John Blackbourn 964d0784be General: Introduce the wp_error_added and wp_error_checked actions.
These actions allow debugging tools to track `WP_Error` instances as they're created and subsequently passed between functions which check for error objects.

Props Shelob9, Mte90, TimothyBlynJacobs, johnbillion

Fixes #40568


Built from https://develop.svn.wordpress.org/trunk@49022


git-svn-id: http://core.svn.wordpress.org/trunk@48784 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2020-09-20 17:44:07 +00:00

236 lines
5.1 KiB
PHP

<?php
/**
* WordPress Error API.
*
* Contains the WP_Error class and the is_wp_error() function.
*
* @package WordPress
*/
/**
* 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.
*
* @since 2.1.0
*/
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->add( $code, $message, $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;
}
/**
* 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.
*/
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 );
}
/**
* 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 ] );
}
}