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