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         private $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         private $error_data = array();
  39
  40         /**
  41          * Initialize the error.
  42          *
  43          * If `$code` is empty, the other parameters will be ignored.
  44          * When `$code` is not empty, `$message` will be used even if
  45          * it is empty. The `$data` parameter will be used only if it
  46          * is not empty.
  47          *
  48          * Though the class is constructed with a single error code and
  49          * message, multiple codes can be added using the `add()` method.
  50          *
  51          * @since 2.1.0
  52          *
  53          * @param string|int $code Error code
  54          * @param string $message Error message
  55          * @param mixed $data Optional. Error data.
  56          * @return WP_Error
  57          */
  58         public function __construct( $code = '', $message = '', $data = '' ) {
  59                 if ( empty($code) )
  60                         return;
  61
  62                 $this->errors[$code][] = $message;
  63
  64                 if ( ! empty($data) )
  65                         $this->error_data[$code] = $data;
  66         }
  67
  68         /**
  69          * Make private properties readable for backwards compatibility.
  70          *
  71          * @since 4.0.0
  72          * @access public
  73          *
  74          * @param string $name Property to get.
  75          * @return mixed Property.
  76          */
  77         public function __get( $name ) {
  78                 return $this->$name;
  79         }
  80
  81         /**
  82          * Make private properties settable for backwards compatibility.
  83          *
  84          * @since 4.0.0
  85          * @access public
  86          *
  87          * @param string $name  Property to set.
  88          * @param mixed  $value Property value.
  89          * @return mixed Newly-set property.
  90          */
  91         public function __set( $name, $value ) {
  92                 return $this->$name = $value;
  93         }
  94
  95         /**
  96          * Make private properties checkable for backwards compatibility.
  97          *
  98          * @since 4.0.0
  99          * @access public
 100          *
 101          * @param string $name Property to check if set.
 102          * @return bool Whether the property is set.
 103          */
 104         public function __isset( $name ) {
 105                 return isset( $this->$name );
 106         }
 107
 108         /**
 109          * Make private properties un-settable for backwards compatibility.
 110          *
 111          * @since 4.0.0
 112          * @access public
 113          *
 114          * @param string $name Property to unset.
 115          */
 116         public function __unset( $name ) {
 117                 unset( $this->$name );
 118         }
 119
 120         /**
 121          * Retrieve all error codes.
 122          *
 123          * @since 2.1.0
 124          * @access public
 125          *
 126          * @return array List of error codes, if available.
 127          */
 128         public function get_error_codes() {
 129                 if ( empty($this->errors) )
 130                         return array();
 131
 132                 return array_keys($this->errors);
 133         }
 134
 135         /**
 136          * Retrieve first error code available.
 137          *
 138          * @since 2.1.0
 139          * @access public
 140          *
 141          * @return string|int Empty string, if no error codes.
 142          */
 143         public function get_error_code() {
 144                 $codes = $this->get_error_codes();
 145
 146                 if ( empty($codes) )
 147                         return '';
 148
 149                 return $codes[0];
 150         }
 151
 152         /**
 153          * Retrieve all error messages or error messages matching code.
 154          *
 155          * @since 2.1.0
 156          *
 157          * @param string|int $code Optional. Retrieve messages matching code, if exists.
 158          * @return array Error strings on success, or empty array on failure (if using code parameter).
 159          */
 160         public function get_error_messages($code = '') {
 161                 // Return all messages if no code specified.
 162                 if ( empty($code) ) {
 163                         $all_messages = array();
 164                         foreach ( (array) $this->errors as $code => $messages )
 165                                 $all_messages = array_merge($all_messages, $messages);
 166
 167                         return $all_messages;
 168                 }
 169
 170                 if ( isset($this->errors[$code]) )
 171                         return $this->errors[$code];
 172                 else
 173                         return array();
 174         }
 175
 176         /**
 177          * Get single error message.
 178          *
 179          * This will get the first message available for the code. If no code is
 180          * given then the first code available will be used.
 181          *
 182          * @since 2.1.0
 183          *
 184          * @param string|int $code Optional. Error code to retrieve message.
 185          * @return string
 186          */
 187         public function get_error_message($code = '') {
 188                 if ( empty($code) )
 189                         $code = $this->get_error_code();
 190                 $messages = $this->get_error_messages($code);
 191                 if ( empty($messages) )
 192                         return '';
 193                 return $messages[0];
 194         }
 195
 196         /**
 197          * Retrieve error data for error code.
 198          *
 199          * @since 2.1.0
 200          *
 201          * @param string|int $code Optional. Error code.
 202          * @return mixed Null, if no errors.
 203          */
 204         public function get_error_data($code = '') {
 205                 if ( empty($code) )
 206                         $code = $this->get_error_code();
 207
 208                 if ( isset($this->error_data[$code]) )
 209                         return $this->error_data[$code];
 210                 return null;
 211         }
 212
 213         /**
 214          * Add an error or append additional message to an existing error.
 215          *
 216          * @since 2.1.0
 217          * @access public
 218          *
 219          * @param string|int $code Error code.
 220          * @param string $message Error message.
 221          * @param mixed $data Optional. Error data.
 222          */
 223         public function add($code, $message, $data = '') {
 224                 $this->errors[$code][] = $message;
 225                 if ( ! empty($data) )
 226                         $this->error_data[$code] = $data;
 227         }
 228
 229         /**
 230          * Add data for error code.
 231          *
 232          * The error code can only contain one error data.
 233          *
 234          * @since 2.1.0
 235          *
 236          * @param mixed $data Error data.
 237          * @param string|int $code Error code.
 238          */
 239         public function add_data($data, $code = '') {
 240                 if ( empty($code) )
 241                         $code = $this->get_error_code();
 242
 243                 $this->error_data[$code] = $data;
 244         }
 245
 246         /**
 247          * Removes the specified error.
 248          *
 249          * This function removes all error messages associated with the specified
 250          * error code, along with any error data for that code.
 251          *
 252          * @since 4.1.0
 253          *
 254          * @param string|int $code Error code.
 255          */
 256         public function remove( $code ) {
 257                 unset( $this->errors[ $code ] );
 258                 unset( $this->error_data[ $code ] );
 259         }
 260 }
 261
 262 /**
 263  * Check whether variable is a WordPress Error.
 264  *
 265  * Returns true if $thing is an object of the WP_Error class.
 266  *
 267  * @since 2.1.0
 268  *
 269  * @param mixed $thing Check if unknown variable is a WP_Error object.
 270  * @return bool True, if WP_Error. False, if not WP_Error.
 271  */
 272 function is_wp_error($thing) {
 273         if ( is_object($thing) && is_a($thing, 'WP_Error') )
 274                 return true;
 275         return false;
 276 }