[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * WordPress Error API.
   4   *
   5   * @package WordPress
   6   */
   7  
   8  /**
   9   * WordPress Error class.
  10   *
  11   * Container for checking for WordPress errors and error messages. Return
  12   * WP_Error and use is_wp_error() to check if this class is returned. Many
  13   * core WordPress functions pass this class in the event of an error and
  14   * if not handled properly will result in code errors.
  15   *
  16   * @since 2.1.0
  17   */
  18  class WP_Error {
  19      /**
  20       * Stores the list of errors.
  21       *
  22       * @since 2.1.0
  23       * @var array
  24       */
  25      public $errors = array();
  26  
  27      /**
  28       * Stores the most recently added data for each error code.
  29       *
  30       * @since 2.1.0
  31       * @var array
  32       */
  33      public $error_data = array();
  34  
  35      /**
  36       * Stores previously added data added for error codes, oldest-to-newest by code.
  37       *
  38       * @since 5.6.0
  39       * @var array[]
  40       */
  41      protected $additional_data = array();
  42  
  43      /**
  44       * Initializes the error.
  45       *
  46       * If `$code` is empty, the other parameters will be ignored.
  47       * When `$code` is not empty, `$message` will be used even if
  48       * it is empty. The `$data` parameter will be used only if it
  49       * is not empty.
  50       *
  51       * Though the class is constructed with a single error code and
  52       * message, multiple codes can be added using the `add()` method.
  53       *
  54       * @since 2.1.0
  55       *
  56       * @param string|int $code    Error code.
  57       * @param string     $message Error message.
  58       * @param mixed      $data    Optional. Error data.
  59       */
  60  	public function __construct( $code = '', $message = '', $data = '' ) {
  61          if ( empty( $code ) ) {
  62              return;
  63          }
  64  
  65          $this->add( $code, $message, $data );
  66      }
  67  
  68      /**
  69       * Retrieves all error codes.
  70       *
  71       * @since 2.1.0
  72       *
  73       * @return array List of error codes, if available.
  74       */
  75  	public function get_error_codes() {
  76          if ( ! $this->has_errors() ) {
  77              return array();
  78          }
  79  
  80          return array_keys( $this->errors );
  81      }
  82  
  83      /**
  84       * Retrieves the first error code available.
  85       *
  86       * @since 2.1.0
  87       *
  88       * @return string|int Empty string, if no error codes.
  89       */
  90  	public function get_error_code() {
  91          $codes = $this->get_error_codes();
  92  
  93          if ( empty( $codes ) ) {
  94              return '';
  95          }
  96  
  97          return $codes[0];
  98      }
  99  
 100      /**
 101       * Retrieves all error messages, or the error messages for the given error code.
 102       *
 103       * @since 2.1.0
 104       *
 105       * @param string|int $code Optional. Retrieve messages matching code, if exists.
 106       * @return string[] Error strings on success, or empty array if there are none.
 107       */
 108  	public function get_error_messages( $code = '' ) {
 109          // Return all messages if no code specified.
 110          if ( empty( $code ) ) {
 111              $all_messages = array();
 112              foreach ( (array) $this->errors as $code => $messages ) {
 113                  $all_messages = array_merge( $all_messages, $messages );
 114              }
 115  
 116              return $all_messages;
 117          }
 118  
 119          if ( isset( $this->errors[ $code ] ) ) {
 120              return $this->errors[ $code ];
 121          } else {
 122              return array();
 123          }
 124      }
 125  
 126      /**
 127       * Gets a single error message.
 128       *
 129       * This will get the first message available for the code. If no code is
 130       * given then the first code available will be used.
 131       *
 132       * @since 2.1.0
 133       *
 134       * @param string|int $code Optional. Error code to retrieve message.
 135       * @return string The error message.
 136       */
 137  	public function get_error_message( $code = '' ) {
 138          if ( empty( $code ) ) {
 139              $code = $this->get_error_code();
 140          }
 141          $messages = $this->get_error_messages( $code );
 142          if ( empty( $messages ) ) {
 143              return '';
 144          }
 145          return $messages[0];
 146      }
 147  
 148      /**
 149       * Retrieves the most recently added error data for an error code.
 150       *
 151       * @since 2.1.0
 152       *
 153       * @param string|int $code Optional. Error code.
 154       * @return mixed Error data, if it exists.
 155       */
 156  	public function get_error_data( $code = '' ) {
 157          if ( empty( $code ) ) {
 158              $code = $this->get_error_code();
 159          }
 160  
 161          if ( isset( $this->error_data[ $code ] ) ) {
 162              return $this->error_data[ $code ];
 163          }
 164      }
 165  
 166      /**
 167       * Verifies if the instance contains errors.
 168       *
 169       * @since 5.1.0
 170       *
 171       * @return bool If the instance contains errors.
 172       */
 173  	public function has_errors() {
 174          if ( ! empty( $this->errors ) ) {
 175              return true;
 176          }
 177          return false;
 178      }
 179  
 180      /**
 181       * Adds an error or appends an additional message to an existing error.
 182       *
 183       * @since 2.1.0
 184       *
 185       * @param string|int $code    Error code.
 186       * @param string     $message Error message.
 187       * @param mixed      $data    Optional. Error data.
 188       */
 189  	public function add( $code, $message, $data = '' ) {
 190          $this->errors[ $code ][] = $message;
 191  
 192          if ( ! empty( $data ) ) {
 193              $this->add_data( $data, $code );
 194          }
 195  
 196          /**
 197           * Fires when an error is added to a WP_Error object.
 198           *
 199           * @since 5.6.0
 200           *
 201           * @param string|int $code     Error code.
 202           * @param string     $message  Error message.
 203           * @param mixed      $data     Error data. Might be empty.
 204           * @param WP_Error   $wp_error The WP_Error object.
 205           */
 206          do_action( 'wp_error_added', $code, $message, $data, $this );
 207      }
 208  
 209      /**
 210       * Adds data to an error with the given code.
 211       *
 212       * @since 2.1.0
 213       * @since 5.6.0 Errors can now contain more than one item of error data. {@see WP_Error::$additional_data}.
 214       *
 215       * @param mixed      $data Error data.
 216       * @param string|int $code Error code.
 217       */
 218  	public function add_data( $data, $code = '' ) {
 219          if ( empty( $code ) ) {
 220              $code = $this->get_error_code();
 221          }
 222  
 223          if ( isset( $this->error_data[ $code ] ) ) {
 224              $this->additional_data[ $code ][] = $this->error_data[ $code ];
 225          }
 226  
 227          $this->error_data[ $code ] = $data;
 228      }
 229  
 230      /**
 231       * Retrieves all error data for an error code in the order in which the data was added.
 232       *
 233       * @since 5.6.0
 234       *
 235       * @param string|int $code Error code.
 236       * @return mixed[] Array of error data, if it exists.
 237       */
 238  	public function get_all_error_data( $code = '' ) {
 239          if ( empty( $code ) ) {
 240              $code = $this->get_error_code();
 241          }
 242  
 243          $data = array();
 244  
 245          if ( isset( $this->additional_data[ $code ] ) ) {
 246              $data = $this->additional_data[ $code ];
 247          }
 248  
 249          if ( isset( $this->error_data[ $code ] ) ) {
 250              $data[] = $this->error_data[ $code ];
 251          }
 252  
 253          return $data;
 254      }
 255  
 256      /**
 257       * Removes the specified error.
 258       *
 259       * This function removes all error messages associated with the specified
 260       * error code, along with any error data for that code.
 261       *
 262       * @since 4.1.0
 263       *
 264       * @param string|int $code Error code.
 265       */
 266  	public function remove( $code ) {
 267          unset( $this->errors[ $code ] );
 268          unset( $this->error_data[ $code ] );
 269          unset( $this->additional_data[ $code ] );
 270      }
 271  
 272      /**
 273       * Merges the errors in the given error object into this one.
 274       *
 275       * @since 5.6.0
 276       *
 277       * @param WP_Error $error Error object to merge.
 278       */
 279  	public function merge_from( WP_Error $error ) {
 280          static::copy_errors( $error, $this );
 281      }
 282  
 283      /**
 284       * Exports the errors in this object into the given one.
 285       *
 286       * @since 5.6.0
 287       *
 288       * @param WP_Error $error Error object to export into.
 289       */
 290  	public function export_to( WP_Error $error ) {
 291          static::copy_errors( $this, $error );
 292      }
 293  
 294      /**
 295       * Copies errors from one WP_Error instance to another.
 296       *
 297       * @since 5.6.0
 298       *
 299       * @param WP_Error $from The WP_Error to copy from.
 300       * @param WP_Error $to   The WP_Error to copy to.
 301       */
 302  	protected static function copy_errors( WP_Error $from, WP_Error $to ) {
 303          foreach ( $from->get_error_codes() as $code ) {
 304              foreach ( $from->get_error_messages( $code ) as $error_message ) {
 305                  $to->add( $code, $error_message );
 306              }
 307  
 308              foreach ( $from->get_all_error_data( $code ) as $data ) {
 309                  $to->add_data( $data, $code );
 310              }
 311          }
 312      }
 313  }