| author | ymh <ymh.work@gmail.com> |
| Wed, 21 Sep 2022 18:19:35 +0200 | |
| changeset 18 | be944660c56a |
| parent 16 | a86126ab1dd4 |
| child 19 | 3d72ae0968f4 |
| permissions | -rw-r--r-- |
| 0 | 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 |
|
|
7
cf61fcea0001
resynchronize code repo with production
ymh <ymh.work@gmail.com>
parents:
5
diff
changeset
|
12 |
* WP_Error and use is_wp_error() to check if this class is returned. Many |
|
cf61fcea0001
resynchronize code repo with production
ymh <ymh.work@gmail.com>
parents:
5
diff
changeset
|
13 |
* core WordPress functions pass this class in the event of an error and |
| 0 | 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 |
*/ |
|
| 5 | 25 |
public $errors = array(); |
| 0 | 26 |
|
27 |
/** |
|
| 18 | 28 |
* Stores the most recently added data for each error code. |
| 0 | 29 |
* |
30 |
* @since 2.1.0 |
|
31 |
* @var array |
|
32 |
*/ |
|
| 5 | 33 |
public $error_data = array(); |
| 0 | 34 |
|
35 |
/** |
|
| 18 | 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. |
|
| 0 | 45 |
* |
| 5 | 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. |
|
| 0 | 50 |
* |
| 5 | 51 |
* Though the class is constructed with a single error code and |
52 |
* message, multiple codes can be added using the `add()` method. |
|
| 0 | 53 |
* |
54 |
* @since 2.1.0 |
|
55 |
* |
|
| 16 | 56 |
* @param string|int $code Error code. |
57 |
* @param string $message Error message. |
|
58 |
* @param mixed $data Optional. Error data. |
|
| 0 | 59 |
*/ |
| 5 | 60 |
public function __construct( $code = '', $message = '', $data = '' ) { |
| 9 | 61 |
if ( empty( $code ) ) { |
| 0 | 62 |
return; |
| 9 | 63 |
} |
| 0 | 64 |
|
| 18 | 65 |
$this->add( $code, $message, $data ); |
| 0 | 66 |
} |
67 |
||
68 |
/** |
|
| 18 | 69 |
* Retrieves all error codes. |
| 0 | 70 |
* |
71 |
* @since 2.1.0 |
|
72 |
* |
|
73 |
* @return array List of error codes, if available. |
|
74 |
*/ |
|
| 5 | 75 |
public function get_error_codes() { |
| 9 | 76 |
if ( ! $this->has_errors() ) { |
| 0 | 77 |
return array(); |
| 9 | 78 |
} |
| 0 | 79 |
|
| 9 | 80 |
return array_keys( $this->errors ); |
| 0 | 81 |
} |
82 |
||
83 |
/** |
|
| 18 | 84 |
* Retrieves the first error code available. |
| 0 | 85 |
* |
86 |
* @since 2.1.0 |
|
87 |
* |
|
88 |
* @return string|int Empty string, if no error codes. |
|
89 |
*/ |
|
| 5 | 90 |
public function get_error_code() { |
| 0 | 91 |
$codes = $this->get_error_codes(); |
92 |
||
| 9 | 93 |
if ( empty( $codes ) ) { |
| 0 | 94 |
return ''; |
| 9 | 95 |
} |
| 0 | 96 |
|
97 |
return $codes[0]; |
|
98 |
} |
|
99 |
||
100 |
/** |
|
| 18 | 101 |
* Retrieves all error messages, or the error messages for the given error code. |
| 0 | 102 |
* |
103 |
* @since 2.1.0 |
|
104 |
* |
|
105 |
* @param string|int $code Optional. Retrieve messages matching code, if exists. |
|
| 18 | 106 |
* @return array Error strings on success, or empty array if there are none. |
| 0 | 107 |
*/ |
| 9 | 108 |
public function get_error_messages( $code = '' ) { |
| 0 | 109 |
// Return all messages if no code specified. |
| 9 | 110 |
if ( empty( $code ) ) { |
| 0 | 111 |
$all_messages = array(); |
| 9 | 112 |
foreach ( (array) $this->errors as $code => $messages ) { |
113 |
$all_messages = array_merge( $all_messages, $messages ); |
|
114 |
} |
|
| 0 | 115 |
|
116 |
return $all_messages; |
|
117 |
} |
|
118 |
||
| 9 | 119 |
if ( isset( $this->errors[ $code ] ) ) { |
120 |
return $this->errors[ $code ]; |
|
121 |
} else { |
|
| 0 | 122 |
return array(); |
| 9 | 123 |
} |
| 0 | 124 |
} |
125 |
||
126 |
/** |
|
| 18 | 127 |
* Gets a single error message. |
| 0 | 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. |
|
| 18 | 135 |
* @return string The error message. |
| 0 | 136 |
*/ |
| 9 | 137 |
public function get_error_message( $code = '' ) { |
138 |
if ( empty( $code ) ) { |
|
| 0 | 139 |
$code = $this->get_error_code(); |
| 9 | 140 |
} |
141 |
$messages = $this->get_error_messages( $code ); |
|
142 |
if ( empty( $messages ) ) { |
|
| 0 | 143 |
return ''; |
| 9 | 144 |
} |
| 0 | 145 |
return $messages[0]; |
146 |
} |
|
147 |
||
148 |
/** |
|
| 18 | 149 |
* Retrieves the most recently added error data for an error code. |
| 0 | 150 |
* |
151 |
* @since 2.1.0 |
|
152 |
* |
|
153 |
* @param string|int $code Optional. Error code. |
|
|
7
cf61fcea0001
resynchronize code repo with production
ymh <ymh.work@gmail.com>
parents:
5
diff
changeset
|
154 |
* @return mixed Error data, if it exists. |
| 0 | 155 |
*/ |
| 9 | 156 |
public function get_error_data( $code = '' ) { |
157 |
if ( empty( $code ) ) { |
|
| 0 | 158 |
$code = $this->get_error_code(); |
| 9 | 159 |
} |
| 0 | 160 |
|
| 9 | 161 |
if ( isset( $this->error_data[ $code ] ) ) { |
162 |
return $this->error_data[ $code ]; |
|
163 |
} |
|
164 |
} |
|
165 |
||
166 |
/** |
|
| 18 | 167 |
* Verifies if the instance contains errors. |
| 9 | 168 |
* |
169 |
* @since 5.1.0 |
|
170 |
* |
|
| 18 | 171 |
* @return bool If the instance contains errors. |
| 9 | 172 |
*/ |
173 |
public function has_errors() { |
|
174 |
if ( ! empty( $this->errors ) ) { |
|
175 |
return true; |
|
176 |
} |
|
177 |
return false; |
|
| 0 | 178 |
} |
179 |
||
180 |
/** |
|
| 18 | 181 |
* Adds an error or appends an additional message to an existing error. |
| 0 | 182 |
* |
183 |
* @since 2.1.0 |
|
184 |
* |
|
| 16 | 185 |
* @param string|int $code Error code. |
186 |
* @param string $message Error message. |
|
187 |
* @param mixed $data Optional. Error data. |
|
| 0 | 188 |
*/ |
| 9 | 189 |
public function add( $code, $message, $data = '' ) { |
190 |
$this->errors[ $code ][] = $message; |
|
| 18 | 191 |
|
| 9 | 192 |
if ( ! empty( $data ) ) { |
| 18 | 193 |
$this->add_data( $data, $code ); |
| 9 | 194 |
} |
| 18 | 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 ); |
|
| 0 | 207 |
} |
208 |
||
209 |
/** |
|
| 18 | 210 |
* Adds data to an error with the given code. |
| 0 | 211 |
* |
212 |
* @since 2.1.0 |
|
| 18 | 213 |
* @since 5.6.0 Errors can now contain more than one item of error data. {@see WP_Error::$additional_data}. |
| 0 | 214 |
* |
| 16 | 215 |
* @param mixed $data Error data. |
| 0 | 216 |
* @param string|int $code Error code. |
217 |
*/ |
|
| 9 | 218 |
public function add_data( $data, $code = '' ) { |
219 |
if ( empty( $code ) ) { |
|
| 0 | 220 |
$code = $this->get_error_code(); |
| 9 | 221 |
} |
| 0 | 222 |
|
| 18 | 223 |
if ( isset( $this->error_data[ $code ] ) ) { |
224 |
$this->additional_data[ $code ][] = $this->error_data[ $code ]; |
|
225 |
} |
|
226 |
||
| 9 | 227 |
$this->error_data[ $code ] = $data; |
| 0 | 228 |
} |
| 5 | 229 |
|
230 |
/** |
|
| 18 | 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 |
/** |
|
| 5 | 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 ] ); |
|
| 18 | 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 |
} |
|
| 5 | 312 |
} |
| 0 | 313 |
} |