[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<int|string, string[]>
  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<int|string, mixed>
  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<int|string, mixed[]>
  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 list<int|string> 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 $messages ) {
 115                  $all_messages = array_merge( $all_messages, $messages );
 116              }
 117  
 118              return $all_messages;
 119          }
 120  
 121          return $this->errors[ $code ] ?? array();
 122      }
 123  
 124      /**
 125       * Gets a single error message.
 126       *
 127       * This will get the first message available for the code. If no code is
 128       * given then the first code available will be used.
 129       *
 130       * @since 2.1.0
 131       *
 132       * @param string|int $code Optional. Error code to retrieve the message for.
 133       *                         Default empty string.
 134       * @return string The error message.
 135       */
 136  	public function get_error_message( $code = '' ) {
 137          if ( empty( $code ) ) {
 138              $code = $this->get_error_code();
 139          }
 140          $messages = $this->get_error_messages( $code );
 141          if ( empty( $messages ) ) {
 142              return '';
 143          }
 144          return $messages[0];
 145      }
 146  
 147      /**
 148       * Retrieves the most recently added error data for an error code.
 149       *
 150       * @since 2.1.0
 151       *
 152       * @param string|int $code Optional. Error code. Default empty string.
 153       * @return mixed Error data, if it exists.
 154       */
 155  	public function get_error_data( $code = '' ) {
 156          if ( empty( $code ) ) {
 157              $code = $this->get_error_code();
 158          }
 159  
 160          return $this->error_data[ $code ] ?? null;
 161      }
 162  
 163      /**
 164       * Verifies if the instance contains errors.
 165       *
 166       * @since 5.1.0
 167       *
 168       * @return bool If the instance contains errors.
 169       */
 170  	public function has_errors() {
 171          return (bool) $this->errors;
 172      }
 173  
 174      /**
 175       * Adds an error or appends an additional message to an existing error.
 176       *
 177       * @since 2.1.0
 178       *
 179       * @param string|int $code    Error code.
 180       * @param string     $message Error message.
 181       * @param mixed      $data    Optional. Error data. Default empty string.
 182       * @return void
 183       */
 184  	public function add( $code, $message, $data = '' ) {
 185          $this->errors[ $code ][] = $message;
 186  
 187          if ( ! empty( $data ) ) {
 188              $this->add_data( $data, $code );
 189          }
 190  
 191          /**
 192           * Fires when an error is added to a WP_Error object.
 193           *
 194           * @since 5.6.0
 195           *
 196           * @param string|int $code     Error code.
 197           * @param string     $message  Error message.
 198           * @param mixed      $data     Error data. Might be empty.
 199           * @param WP_Error   $wp_error The WP_Error object.
 200           */
 201          do_action( 'wp_error_added', $code, $message, $data, $this );
 202      }
 203  
 204      /**
 205       * Adds data to an error with the given code.
 206       *
 207       * @since 2.1.0
 208       * @since 5.6.0 Errors can now contain more than one item of error data. {@see WP_Error::$additional_data}.
 209       *
 210       * @param mixed      $data Error data.
 211       * @param string|int $code Error code.
 212       * @return void
 213       */
 214  	public function add_data( $data, $code = '' ) {
 215          if ( empty( $code ) ) {
 216              $code = $this->get_error_code();
 217          }
 218  
 219          if ( isset( $this->error_data[ $code ] ) ) {
 220              $this->additional_data[ $code ][] = $this->error_data[ $code ];
 221          }
 222  
 223          $this->error_data[ $code ] = $data;
 224      }
 225  
 226      /**
 227       * Retrieves all error data for an error code in the order in which the data was added.
 228       *
 229       * @since 5.6.0
 230       *
 231       * @param string|int $code Error code.
 232       * @return mixed[] Array of error data, if it exists.
 233       */
 234  	public function get_all_error_data( $code = '' ) {
 235          if ( empty( $code ) ) {
 236              $code = $this->get_error_code();
 237          }
 238  
 239          $data = array();
 240  
 241          if ( isset( $this->additional_data[ $code ] ) ) {
 242              $data = $this->additional_data[ $code ];
 243          }
 244  
 245          if ( isset( $this->error_data[ $code ] ) ) {
 246              $data[] = $this->error_data[ $code ];
 247          }
 248  
 249          return $data;
 250      }
 251  
 252      /**
 253       * Removes the specified error.
 254       *
 255       * This function removes all error messages associated with the specified
 256       * error code, along with any error data for that code.
 257       *
 258       * @since 4.1.0
 259       *
 260       * @param string|int $code Error code.
 261       * @return void
 262       */
 263  	public function remove( $code ) {
 264          unset( $this->errors[ $code ] );
 265          unset( $this->error_data[ $code ] );
 266          unset( $this->additional_data[ $code ] );
 267      }
 268  
 269      /**
 270       * Merges the errors in the given error object into this one.
 271       *
 272       * @since 5.6.0
 273       *
 274       * @param WP_Error $error Error object to merge.
 275       * @return void
 276       */
 277  	public function merge_from( WP_Error $error ) {
 278          static::copy_errors( $error, $this );
 279      }
 280  
 281      /**
 282       * Exports the errors in this object into the given one.
 283       *
 284       * @since 5.6.0
 285       *
 286       * @param WP_Error $error Error object to export into.
 287       * @return void
 288       */
 289  	public function export_to( WP_Error $error ) {
 290          static::copy_errors( $this, $error );
 291      }
 292  
 293      /**
 294       * Copies errors from one WP_Error instance to another.
 295       *
 296       * @since 5.6.0
 297       *
 298       * @param WP_Error $from The WP_Error to copy from.
 299       * @param WP_Error $to   The WP_Error to copy to.
 300       * @return void
 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  }