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 {@link is_wp_error()} to check if this class is returned.
  15  * Many 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          * @access private
  28          */
  29         var $errors = array();
  30
  31         /**
  32          * Stores the list of data for error codes.
  33          *
  34          * @since 2.1.0
  35          * @var array
  36          * @access private
  37          */
  38         var $error_data = array();
  39
  40         /**
  41          * PHP4 Constructor - Sets up error message.
  42          *
  43          * If code parameter is empty then nothing will be done. It is possible to
  44          * add multiple messages to the same code, but with other methods in the
  45          * class.
  46          *
  47          * All parameters are optional, but if the code parameter is set, then the
  48          * data parameter is optional.
  49          *
  50          * @since 2.1.0
  51          *
  52          * @param string|int $code Error code
  53          * @param string $message Error message
  54          * @param mixed $data Optional. Error data.
  55          * @return WP_Error
  56          */
  57         function WP_Error($code = '', $message = '', $data = '') {
  58                 if ( empty($code) )
  59                         return;
  60
  61                 $this->errors[$code][] = $message;
  62
  63                 if ( ! empty($data) )
  64                         $this->error_data[$code] = $data;
  65         }
  66
  67         /**
  68          * Retrieve all error codes.
  69          *
  70          * @since 2.1.0
  71          * @access public
  72          *
  73          * @return array List of error codes, if avaiable.
  74          */
  75         function get_error_codes() {
  76                 if ( empty($this->errors) )
  77                         return array();
  78
  79                 return array_keys($this->errors);
  80         }
  81
  82         /**
  83          * Retrieve first error code available.
  84          *
  85          * @since 2.1.0
  86          * @access public
  87          *
  88          * @return string|int Empty string, if no error codes.
  89          */
  90         function get_error_code() {
  91                 $codes = $this->get_error_codes();
  92
  93                 if ( empty($codes) )
  94                         return '';
  95
  96                 return $codes[0];
  97         }
  98
  99         /**
 100          * Retrieve all error messages or error messages matching code.
 101          *
 102          * @since 2.1.0
 103          *
 104          * @param string|int $code Optional. Retrieve messages matching code, if exists.
 105          * @return array Error strings on success, or empty array on failure (if using codee parameter).
 106          */
 107         function get_error_messages($code = '') {
 108                 // Return all messages if no code specified.
 109                 if ( empty($code) ) {
 110                         $all_messages = array();
 111                         foreach ( (array) $this->errors as $code => $messages )
 112                                 $all_messages = array_merge($all_messages, $messages);
 113
 114                         return $all_messages;
 115                 }
 116
 117                 if ( isset($this->errors[$code]) )
 118                         return $this->errors[$code];
 119                 else
 120                         return array();
 121         }
 122
 123         /**
 124          * Get single error message.
 125          *
 126          * This will get the first message available for the code. If no code is
 127          * given then the first code available will be used.
 128          *
 129          * @since 2.1.0
 130          *
 131          * @param string|int $code Optional. Error code to retrieve message.
 132          * @return string
 133          */
 134         function get_error_message($code = '') {
 135                 if ( empty($code) )
 136                         $code = $this->get_error_code();
 137                 $messages = $this->get_error_messages($code);
 138                 if ( empty($messages) )
 139                         return '';
 140                 return $messages[0];
 141         }
 142
 143         /**
 144          * Retrieve error data for error code.
 145          *
 146          * @since 2.1.0
 147          *
 148          * @param string|int $code Optional. Error code.
 149          * @return mixed Null, if no errors.
 150          */
 151         function get_error_data($code = '') {
 152                 if ( empty($code) )
 153                         $code = $this->get_error_code();
 154
 155                 if ( isset($this->error_data[$code]) )
 156                         return $this->error_data[$code];
 157                 return null;
 158         }
 159
 160         /**
 161          * Append more error messages to list of error messages.
 162          *
 163          * @since 2.1.0
 164          * @access public
 165          *
 166          * @param string|int $code Error code.
 167          * @param string $message Error message.
 168          * @param mixed $data Optional. Error data.
 169          */
 170         function add($code, $message, $data = '') {
 171                 $this->errors[$code][] = $message;
 172                 if ( ! empty($data) )
 173                         $this->error_data[$code] = $data;
 174         }
 175
 176         /**
 177          * Add data for error code.
 178          *
 179          * The error code can only contain one error data.
 180          *
 181          * @since 2.1.0
 182          *
 183          * @param mixed $data Error data.
 184          * @param string|int $code Error code.
 185          */
 186         function add_data($data, $code = '') {
 187                 if ( empty($code) )
 188                         $code = $this->get_error_code();
 189
 190                 $this->error_data[$code] = $data;
 191         }
 192 }
 193
 194 /**
 195  * Check whether variable is a WordPress Error.
 196  *
 197  * Looks at the object and if a WP_Error class. Does not check to see if the
 198  * parent is also WP_Error, so can't inherit WP_Error and still use this
 199  * function.
 200  *
 201  * @since 2.1.0
 202  *
 203  * @param mixed $thing Check if unknown variable is WordPress Error object.
 204  * @return bool True, if WP_Error. False, if not WP_Error.
 205  */
 206 function is_wp_error($thing) {
 207         if ( is_object($thing) && is_a($thing, 'WP_Error') )
 208                 return true;
 209         return false;
 210 }
 211
 212 ?>