25 * @var array |
23 * @var array |
26 */ |
24 */ |
27 public $errors = array(); |
25 public $errors = array(); |
28 |
26 |
29 /** |
27 /** |
30 * Stores the list of data for error codes. |
28 * Stores the most recently added data for each error code. |
31 * |
29 * |
32 * @since 2.1.0 |
30 * @since 2.1.0 |
33 * @var array |
31 * @var array |
34 */ |
32 */ |
35 public $error_data = array(); |
33 public $error_data = array(); |
36 |
34 |
37 /** |
35 /** |
38 * Initialize the error. |
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. |
39 * |
45 * |
40 * If `$code` is empty, the other parameters will be ignored. |
46 * If `$code` is empty, the other parameters will be ignored. |
41 * When `$code` is not empty, `$message` will be used even if |
47 * When `$code` is not empty, `$message` will be used even if |
42 * it is empty. The `$data` parameter will be used only if it |
48 * it is empty. The `$data` parameter will be used only if it |
43 * is not empty. |
49 * is not empty. |
54 public function __construct( $code = '', $message = '', $data = '' ) { |
60 public function __construct( $code = '', $message = '', $data = '' ) { |
55 if ( empty( $code ) ) { |
61 if ( empty( $code ) ) { |
56 return; |
62 return; |
57 } |
63 } |
58 |
64 |
59 $this->errors[ $code ][] = $message; |
65 $this->add( $code, $message, $data ); |
60 |
66 } |
61 if ( ! empty( $data ) ) { |
67 |
62 $this->error_data[ $code ] = $data; |
68 /** |
63 } |
69 * Retrieves all error codes. |
64 } |
|
65 |
|
66 /** |
|
67 * Retrieve all error codes. |
|
68 * |
70 * |
69 * @since 2.1.0 |
71 * @since 2.1.0 |
70 * |
72 * |
71 * @return array List of error codes, if available. |
73 * @return array List of error codes, if available. |
72 */ |
74 */ |
94 |
96 |
95 return $codes[0]; |
97 return $codes[0]; |
96 } |
98 } |
97 |
99 |
98 /** |
100 /** |
99 * Retrieve all error messages or error messages matching code. |
101 * Retrieves all error messages, or the error messages for the given error code. |
100 * |
102 * |
101 * @since 2.1.0 |
103 * @since 2.1.0 |
102 * |
104 * |
103 * @param string|int $code Optional. Retrieve messages matching code, if exists. |
105 * @param string|int $code Optional. Retrieve messages matching code, if exists. |
104 * @return array Error strings on success, or empty array on failure (if using code parameter). |
106 * @return array Error strings on success, or empty array if there are none. |
105 */ |
107 */ |
106 public function get_error_messages( $code = '' ) { |
108 public function get_error_messages( $code = '' ) { |
107 // Return all messages if no code specified. |
109 // Return all messages if no code specified. |
108 if ( empty( $code ) ) { |
110 if ( empty( $code ) ) { |
109 $all_messages = array(); |
111 $all_messages = array(); |
120 return array(); |
122 return array(); |
121 } |
123 } |
122 } |
124 } |
123 |
125 |
124 /** |
126 /** |
125 * Get single error message. |
127 * Gets a single error message. |
126 * |
128 * |
127 * This will get the first message available for the code. If no code is |
129 * This will get the first message available for the code. If no code is |
128 * given then the first code available will be used. |
130 * given then the first code available will be used. |
129 * |
131 * |
130 * @since 2.1.0 |
132 * @since 2.1.0 |
131 * |
133 * |
132 * @param string|int $code Optional. Error code to retrieve message. |
134 * @param string|int $code Optional. Error code to retrieve message. |
133 * @return string |
135 * @return string The error message. |
134 */ |
136 */ |
135 public function get_error_message( $code = '' ) { |
137 public function get_error_message( $code = '' ) { |
136 if ( empty( $code ) ) { |
138 if ( empty( $code ) ) { |
137 $code = $this->get_error_code(); |
139 $code = $this->get_error_code(); |
138 } |
140 } |
160 return $this->error_data[ $code ]; |
162 return $this->error_data[ $code ]; |
161 } |
163 } |
162 } |
164 } |
163 |
165 |
164 /** |
166 /** |
165 * Verify if the instance contains errors. |
167 * Verifies if the instance contains errors. |
166 * |
168 * |
167 * @since 5.1.0 |
169 * @since 5.1.0 |
168 * |
170 * |
169 * @return bool |
171 * @return bool If the instance contains errors. |
170 */ |
172 */ |
171 public function has_errors() { |
173 public function has_errors() { |
172 if ( ! empty( $this->errors ) ) { |
174 if ( ! empty( $this->errors ) ) { |
173 return true; |
175 return true; |
174 } |
176 } |
175 return false; |
177 return false; |
176 } |
178 } |
177 |
179 |
178 /** |
180 /** |
179 * Add an error or append additional message to an existing error. |
181 * Adds an error or appends an additional message to an existing error. |
180 * |
182 * |
181 * @since 2.1.0 |
183 * @since 2.1.0 |
182 * |
184 * |
183 * @param string|int $code Error code. |
185 * @param string|int $code Error code. |
184 * @param string $message Error message. |
186 * @param string $message Error message. |
185 * @param mixed $data Optional. Error data. |
187 * @param mixed $data Optional. Error data. |
186 */ |
188 */ |
187 public function add( $code, $message, $data = '' ) { |
189 public function add( $code, $message, $data = '' ) { |
188 $this->errors[ $code ][] = $message; |
190 $this->errors[ $code ][] = $message; |
|
191 |
189 if ( ! empty( $data ) ) { |
192 if ( ! empty( $data ) ) { |
190 $this->error_data[ $code ] = $data; |
193 $this->add_data( $data, $code ); |
191 } |
194 } |
192 } |
195 |
193 |
196 /** |
194 /** |
197 * Fires when an error is added to a WP_Error object. |
195 * Add data for error code. |
198 * |
196 * |
199 * @since 5.6.0 |
197 * The error code can only contain one error data. |
200 * |
198 * |
201 * @param string|int $code Error code. |
199 * @since 2.1.0 |
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}. |
200 * |
214 * |
201 * @param mixed $data Error data. |
215 * @param mixed $data Error data. |
202 * @param string|int $code Error code. |
216 * @param string|int $code Error code. |
203 */ |
217 */ |
204 public function add_data( $data, $code = '' ) { |
218 public function add_data( $data, $code = '' ) { |
205 if ( empty( $code ) ) { |
219 if ( empty( $code ) ) { |
206 $code = $this->get_error_code(); |
220 $code = $this->get_error_code(); |
207 } |
221 } |
208 |
222 |
|
223 if ( isset( $this->error_data[ $code ] ) ) { |
|
224 $this->additional_data[ $code ][] = $this->error_data[ $code ]; |
|
225 } |
|
226 |
209 $this->error_data[ $code ] = $data; |
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; |
210 } |
254 } |
211 |
255 |
212 /** |
256 /** |
213 * Removes the specified error. |
257 * Removes the specified error. |
214 * |
258 * |
220 * @param string|int $code Error code. |
264 * @param string|int $code Error code. |
221 */ |
265 */ |
222 public function remove( $code ) { |
266 public function remove( $code ) { |
223 unset( $this->errors[ $code ] ); |
267 unset( $this->errors[ $code ] ); |
224 unset( $this->error_data[ $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 } |
225 } |
312 } |
226 } |
313 } |