WordPress 4.0
[autoinstalls/wordpress.git] / wp-includes / class-wp-error.php
1 <?php
2 /**
3  * WordPress Error API.
4  *
5  * Contains the WP_Error class and the is_wp_error() function.
6  *
7  * @package WordPress
8  */
9
10 /**
11  * WordPress Error class.
12  *
13  * Container for checking for WordPress errors and error messages. Return
14  * WP_Error and use {@link is_wp_error()} to check if this class is returned.
15  * Many core WordPress functions pass this class in the event of an error and
16  * if not handled properly will result in code errors.
17  *
18  * @package WordPress
19  * @since 2.1.0
20  */
21 class WP_Error {
22         /**
23          * Stores the list of errors.
24          *
25          * @since 2.1.0
26          * @var array
27          * @access private
28          */
29         private $errors = array();
30
31         /**
32          * Stores the list of data for error codes.
33          *
34          * @since 2.1.0
35          * @var array
36          * @access private
37          */
38         private $error_data = array();
39
40         /**
41          * Initialize the error.
42          *
43          * If `$code` is empty, the other parameters will be ignored.
44          * When `$code` is not empty, `$message` will be used even if
45          * it is empty. The `$data` parameter will be used only if it
46          * is not empty.
47          *
48          * Though the class is constructed with a single error code and
49          * message, multiple codes can be added using the `add()` method.
50          *
51          * @since 2.1.0
52          *
53          * @param string|int $code Error code
54          * @param string $message Error message
55          * @param mixed $data Optional. Error data.
56          * @return WP_Error
57          */
58         public function __construct( $code = '', $message = '', $data = '' ) {
59                 if ( empty($code) )
60                         return;
61
62                 $this->errors[$code][] = $message;
63
64                 if ( ! empty($data) )
65                         $this->error_data[$code] = $data;
66         }
67
68         /**
69          * Make private properties readable for backwards compatibility.
70          *
71          * @since 4.0.0
72          * @access public
73          *
74          * @param string $name Property to get.
75          * @return mixed Property.
76          */
77         public function __get( $name ) {
78                 return $this->$name;
79         }
80
81         /**
82          * Make private properties settable for backwards compatibility.
83          *
84          * @since 4.0.0
85          * @access public
86          *
87          * @param string $name  Property to set.
88          * @param mixed  $value Property value.
89          * @return mixed Newly-set property.
90          */
91         public function __set( $name, $value ) {
92                 return $this->$name = $value;
93         }
94
95         /**
96          * Make private properties checkable for backwards compatibility.
97          *
98          * @since 4.0.0
99          * @access public
100          *
101          * @param string $name Property to check if set.
102          * @return bool Whether the property is set.
103          */
104         public function __isset( $name ) {
105                 return isset( $this->$name );
106         }
107
108         /**
109          * Make private properties un-settable for backwards compatibility.
110          *
111          * @since 4.0.0
112          * @access public
113          *
114          * @param string $name Property to unset.
115          */
116         public function __unset( $name ) {
117                 unset( $this->$name );
118         }
119
120         /**
121          * Retrieve all error codes.
122          *
123          * @since 2.1.0
124          * @access public
125          *
126          * @return array List of error codes, if available.
127          */
128         public function get_error_codes() {
129                 if ( empty($this->errors) )
130                         return array();
131
132                 return array_keys($this->errors);
133         }
134
135         /**
136          * Retrieve first error code available.
137          *
138          * @since 2.1.0
139          * @access public
140          *
141          * @return string|int Empty string, if no error codes.
142          */
143         public function get_error_code() {
144                 $codes = $this->get_error_codes();
145
146                 if ( empty($codes) )
147                         return '';
148
149                 return $codes[0];
150         }
151
152         /**
153          * Retrieve all error messages or error messages matching code.
154          *
155          * @since 2.1.0
156          *
157          * @param string|int $code Optional. Retrieve messages matching code, if exists.
158          * @return array Error strings on success, or empty array on failure (if using code parameter).
159          */
160         public function get_error_messages($code = '') {
161                 // Return all messages if no code specified.
162                 if ( empty($code) ) {
163                         $all_messages = array();
164                         foreach ( (array) $this->errors as $code => $messages )
165                                 $all_messages = array_merge($all_messages, $messages);
166
167                         return $all_messages;
168                 }
169
170                 if ( isset($this->errors[$code]) )
171                         return $this->errors[$code];
172                 else
173                         return array();
174         }
175
176         /**
177          * Get single error message.
178          *
179          * This will get the first message available for the code. If no code is
180          * given then the first code available will be used.
181          *
182          * @since 2.1.0
183          *
184          * @param string|int $code Optional. Error code to retrieve message.
185          * @return string
186          */
187         public function get_error_message($code = '') {
188                 if ( empty($code) )
189                         $code = $this->get_error_code();
190                 $messages = $this->get_error_messages($code);
191                 if ( empty($messages) )
192                         return '';
193                 return $messages[0];
194         }
195
196         /**
197          * Retrieve error data for error code.
198          *
199          * @since 2.1.0
200          *
201          * @param string|int $code Optional. Error code.
202          * @return mixed Null, if no errors.
203          */
204         public function get_error_data($code = '') {
205                 if ( empty($code) )
206                         $code = $this->get_error_code();
207
208                 if ( isset($this->error_data[$code]) )
209                         return $this->error_data[$code];
210                 return null;
211         }
212
213         /**
214          * Add an error or append additional message to an existing error.
215          *
216          * @since 2.1.0
217          * @access public
218          *
219          * @param string|int $code Error code.
220          * @param string $message Error message.
221          * @param mixed $data Optional. Error data.
222          */
223         public function add($code, $message, $data = '') {
224                 $this->errors[$code][] = $message;
225                 if ( ! empty($data) )
226                         $this->error_data[$code] = $data;
227         }
228
229         /**
230          * Add data for error code.
231          *
232          * The error code can only contain one error data.
233          *
234          * @since 2.1.0
235          *
236          * @param mixed $data Error data.
237          * @param string|int $code Error code.
238          */
239         public function add_data($data, $code = '') {
240                 if ( empty($code) )
241                         $code = $this->get_error_code();
242
243                 $this->error_data[$code] = $data;
244         }
245 }
246
247 /**
248  * Check whether variable is a WordPress Error.
249  *
250  * Returns true if $thing is an object of the WP_Error class.
251  *
252  * @since 2.1.0
253  *
254  * @param mixed $thing Check if unknown variable is a WP_Error object.
255  * @return bool True, if WP_Error. False, if not WP_Error.
256  */
257 function is_wp_error($thing) {
258         if ( is_object($thing) && is_a($thing, 'WP_Error') )
259                 return true;
260         return false;
261 }