wp-includes/class-wp-error.php

   1 <?php
   2 /**
   3  * WordPress Error API.
   4  *
   5  * Contains the WP_Error class and the is_wp_error() function.
   6  *
   7  * @package WordPress
   8  */
   9
  10 /**
  11  * WordPress Error class.
  12  *
  13  * Container for checking for WordPress errors and error messages. Return
  14  * WP_Error and use is_wp_error() to check if this class is returned. Many
  15  * core WordPress functions pass this class in the event of an error and
  16  * if not handled properly will result in code errors.
  17  *
  18  * @package WordPress
  19  * @since 2.1.0
  20  */
  21 class WP_Error {
  22         /**
  23          * Stores the list of errors.
  24          *
  25          * @since 2.1.0
  26          * @var array
  27          */
  28         public $errors = array();
  29
  30         /**
  31          * Stores the list of data for error codes.
  32          *
  33          * @since 2.1.0
  34          * @var array
  35          */
  36         public $error_data = array();
  37
  38         /**
  39          * Initialize the error.
  40          *
  41          * If `$code` is empty, the other parameters will be ignored.
  42          * When `$code` is not empty, `$message` will be used even if
  43          * it is empty. The `$data` parameter will be used only if it
  44          * is not empty.
  45          *
  46          * Though the class is constructed with a single error code and
  47          * message, multiple codes can be added using the `add()` method.
  48          *
  49          * @since 2.1.0
  50          *
  51          * @param string|int $code Error code
  52          * @param string $message Error message
  53          * @param mixed $data Optional. Error data.
  54          */
  55         public function __construct( $code = '', $message = '', $data = '' ) {
  56                 if ( empty($code) )
  57                         return;
  58
  59                 $this->errors[$code][] = $message;
  60
  61                 if ( ! empty($data) )
  62                         $this->error_data[$code] = $data;
  63         }
  64
  65         /**
  66          * Retrieve all error codes.
  67          *
  68          * @since 2.1.0
  69          * @access public
  70          *
  71          * @return array List of error codes, if available.
  72          */
  73         public function get_error_codes() {
  74                 if ( empty($this->errors) )
  75                         return array();
  76
  77                 return array_keys($this->errors);
  78         }
  79
  80         /**
  81          * Retrieve first error code available.
  82          *
  83          * @since 2.1.0
  84          * @access public
  85          *
  86          * @return string|int Empty string, if no error codes.
  87          */
  88         public function get_error_code() {
  89                 $codes = $this->get_error_codes();
  90
  91                 if ( empty($codes) )
  92                         return '';
  93
  94                 return $codes[0];
  95         }
  96
  97         /**
  98          * Retrieve all error messages or error messages matching code.
  99          *
 100          * @since 2.1.0
 101          *
 102          * @param string|int $code Optional. Retrieve messages matching code, if exists.
 103          * @return array Error strings on success, or empty array on failure (if using code parameter).
 104          */
 105         public function get_error_messages($code = '') {
 106                 // Return all messages if no code specified.
 107                 if ( empty($code) ) {
 108                         $all_messages = array();
 109                         foreach ( (array) $this->errors as $code => $messages )
 110                                 $all_messages = array_merge($all_messages, $messages);
 111
 112                         return $all_messages;
 113                 }
 114
 115                 if ( isset($this->errors[$code]) )
 116                         return $this->errors[$code];
 117                 else
 118                         return array();
 119         }
 120
 121         /**
 122          * Get single error message.
 123          *
 124          * This will get the first message available for the code. If no code is
 125          * given then the first code available will be used.
 126          *
 127          * @since 2.1.0
 128          *
 129          * @param string|int $code Optional. Error code to retrieve message.
 130          * @return string
 131          */
 132         public function get_error_message($code = '') {
 133                 if ( empty($code) )
 134                         $code = $this->get_error_code();
 135                 $messages = $this->get_error_messages($code);
 136                 if ( empty($messages) )
 137                         return '';
 138                 return $messages[0];
 139         }
 140
 141         /**
 142          * Retrieve error data for error code.
 143          *
 144          * @since 2.1.0
 145          *
 146          * @param string|int $code Optional. Error code.
 147          * @return mixed Error data, if it exists.
 148          */
 149         public function get_error_data($code = '') {
 150                 if ( empty($code) )
 151                         $code = $this->get_error_code();
 152
 153                 if ( isset($this->error_data[$code]) )
 154                         return $this->error_data[$code];
 155         }
 156
 157         /**
 158          * Add an error or append additional message to an existing error.
 159          *
 160          * @since 2.1.0
 161          * @access public
 162          *
 163          * @param string|int $code Error code.
 164          * @param string $message Error message.
 165          * @param mixed $data Optional. Error data.
 166          */
 167         public function add($code, $message, $data = '') {
 168                 $this->errors[$code][] = $message;
 169                 if ( ! empty($data) )
 170                         $this->error_data[$code] = $data;
 171         }
 172
 173         /**
 174          * Add data for error code.
 175          *
 176          * The error code can only contain one error data.
 177          *
 178          * @since 2.1.0
 179          *
 180          * @param mixed $data Error data.
 181          * @param string|int $code Error code.
 182          */
 183         public function add_data($data, $code = '') {
 184                 if ( empty($code) )
 185                         $code = $this->get_error_code();
 186
 187                 $this->error_data[$code] = $data;
 188         }
 189
 190         /**
 191          * Removes the specified error.
 192          *
 193          * This function removes all error messages associated with the specified
 194          * error code, along with any error data for that code.
 195          *
 196          * @since 4.1.0
 197          *
 198          * @param string|int $code Error code.
 199          */
 200         public function remove( $code ) {
 201                 unset( $this->errors[ $code ] );
 202                 unset( $this->error_data[ $code ] );
 203         }
 204 }
 205
 206 /**
 207  * Check whether variable is a WordPress Error.
 208  *
 209  * Returns true if $thing is an object of the WP_Error class.
 210  *
 211  * @since 2.1.0
 212  *
 213  * @param mixed $thing Check if unknown variable is a WP_Error object.
 214  * @return bool True, if WP_Error. False, if not WP_Error.
 215  */
 216 function is_wp_error( $thing ) {
 217         return ( $thing instanceof WP_Error );
 218 }