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