"Fossies" - the Fresh Open Source Software Archive

Member "wordpress/wp-includes/class-wp-error.php" (9 Oct 2020, 7302 Bytes) of package /linux/www/wordpress-5.7-RC1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) PHP source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "class-wp-error.php" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 5.5.3_vs_5.6.

    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 array 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 }