WordPress 3.4
[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         var $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         var $error_data = array();
39
40         /**
41          * Constructor - Sets up error message.
42          *
43          * If code parameter is empty then nothing will be done. It is possible to
44          * add multiple messages to the same code, but with other methods in the
45          * class.
46          *
47          * All parameters are optional, but if the code parameter is set, then the
48          * data parameter is optional.
49          *
50          * @since 2.1.0
51          *
52          * @param string|int $code Error code
53          * @param string $message Error message
54          * @param mixed $data Optional. Error data.
55          * @return WP_Error
56          */
57         function __construct($code = '', $message = '', $data = '') {
58                 if ( empty($code) )
59                         return;
60
61                 $this->errors[$code][] = $message;
62
63                 if ( ! empty($data) )
64                         $this->error_data[$code] = $data;
65         }
66
67         /**
68          * Retrieve all error codes.
69          *
70          * @since 2.1.0
71          * @access public
72          *
73          * @return array List of error codes, if available.
74          */
75         function get_error_codes() {
76                 if ( empty($this->errors) )
77                         return array();
78
79                 return array_keys($this->errors);
80         }
81
82         /**
83          * Retrieve first error code available.
84          *
85          * @since 2.1.0
86          * @access public
87          *
88          * @return string|int Empty string, if no error codes.
89          */
90         function get_error_code() {
91                 $codes = $this->get_error_codes();
92
93                 if ( empty($codes) )
94                         return '';
95
96                 return $codes[0];
97         }
98
99         /**
100          * Retrieve all error messages or error messages matching code.
101          *
102          * @since 2.1.0
103          *
104          * @param string|int $code Optional. Retrieve messages matching code, if exists.
105          * @return array Error strings on success, or empty array on failure (if using code parameter).
106          */
107         function get_error_messages($code = '') {
108                 // Return all messages if no code specified.
109                 if ( empty($code) ) {
110                         $all_messages = array();
111                         foreach ( (array) $this->errors as $code => $messages )
112                                 $all_messages = array_merge($all_messages, $messages);
113
114                         return $all_messages;
115                 }
116
117                 if ( isset($this->errors[$code]) )
118                         return $this->errors[$code];
119                 else
120                         return array();
121         }
122
123         /**
124          * Get single error message.
125          *
126          * This will get the first message available for the code. If no code is
127          * given then the first code available will be used.
128          *
129          * @since 2.1.0
130          *
131          * @param string|int $code Optional. Error code to retrieve message.
132          * @return string
133          */
134         function get_error_message($code = '') {
135                 if ( empty($code) )
136                         $code = $this->get_error_code();
137                 $messages = $this->get_error_messages($code);
138                 if ( empty($messages) )
139                         return '';
140                 return $messages[0];
141         }
142
143         /**
144          * Retrieve error data for error code.
145          *
146          * @since 2.1.0
147          *
148          * @param string|int $code Optional. Error code.
149          * @return mixed Null, if no errors.
150          */
151         function get_error_data($code = '') {
152                 if ( empty($code) )
153                         $code = $this->get_error_code();
154
155                 if ( isset($this->error_data[$code]) )
156                         return $this->error_data[$code];
157                 return null;
158         }
159
160         /**
161          * Append more error messages to list of error messages.
162          *
163          * @since 2.1.0
164          * @access public
165          *
166          * @param string|int $code Error code.
167          * @param string $message Error message.
168          * @param mixed $data Optional. Error data.
169          */
170         function add($code, $message, $data = '') {
171                 $this->errors[$code][] = $message;
172                 if ( ! empty($data) )
173                         $this->error_data[$code] = $data;
174         }
175
176         /**
177          * Add data for error code.
178          *
179          * The error code can only contain one error data.
180          *
181          * @since 2.1.0
182          *
183          * @param mixed $data Error data.
184          * @param string|int $code Error code.
185          */
186         function add_data($data, $code = '') {
187                 if ( empty($code) )
188                         $code = $this->get_error_code();
189
190                 $this->error_data[$code] = $data;
191         }
192 }
193
194 /**
195  * Check whether variable is a WordPress Error.
196  *
197  * Looks at the object and if a WP_Error class. Does not check to see if the
198  * parent is also WP_Error, so can't inherit WP_Error and still use this
199  * function.
200  *
201  * @since 2.1.0
202  *
203  * @param mixed $thing Check if unknown variable is WordPress Error object.
204  * @return bool True, if WP_Error. False, if not WP_Error.
205  */
206 function is_wp_error($thing) {
207         if ( is_object($thing) && is_a($thing, 'WP_Error') )
208                 return true;
209         return false;
210 }