/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 is_wp_error() to check if this class is returned. Many 
  15. * 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. */ 
  28. public $errors = array(); 
  29.  
  30. /** 
  31. * Stores the list of data for error codes. 
  32. * 
  33. * @since 2.1.0 
  34. * @var array 
  35. */ 
  36. public $error_data = array(); 
  37.  
  38. /** 
  39. * Initialize the error. 
  40. * 
  41. * If `$code` is empty, the other parameters will be ignored. 
  42. * When `$code` is not empty, `$message` will be used even if 
  43. * it is empty. The `$data` parameter will be used only if it 
  44. * is not empty. 
  45. * 
  46. * Though the class is constructed with a single error code and 
  47. * message, multiple codes can be added using the `add()` method. 
  48. * 
  49. * @since 2.1.0 
  50. * 
  51. * @param string|int $code Error code 
  52. * @param string $message Error message 
  53. * @param mixed $data Optional. Error data. 
  54. */ 
  55. public function __construct( $code = '', $message = '', $data = '' ) { 
  56. if ( empty($code) ) 
  57. return; 
  58.  
  59. $this->errors[$code][] = $message; 
  60.  
  61. if ( ! empty($data) ) 
  62. $this->error_data[$code] = $data; 
  63.  
  64. /** 
  65. * Retrieve all error codes. 
  66. * 
  67. * @since 2.1.0 
  68. * @access public 
  69. * 
  70. * @return array List of error codes, if available. 
  71. */ 
  72. public function get_error_codes() { 
  73. if ( empty($this->errors) ) 
  74. return array(); 
  75.  
  76. return array_keys($this->errors); 
  77.  
  78. /** 
  79. * Retrieve first error code available. 
  80. * 
  81. * @since 2.1.0 
  82. * @access public 
  83. * 
  84. * @return string|int Empty string, if no error codes. 
  85. */ 
  86. public function get_error_code() { 
  87. $codes = $this->get_error_codes(); 
  88.  
  89. if ( empty($codes) ) 
  90. return ''; 
  91.  
  92. return $codes[0]; 
  93.  
  94. /** 
  95. * Retrieve all error messages or error messages matching code. 
  96. * 
  97. * @since 2.1.0 
  98. * 
  99. * @param string|int $code Optional. Retrieve messages matching code, if exists. 
  100. * @return array Error strings on success, or empty array on failure (if using code parameter). 
  101. */ 
  102. public function get_error_messages($code = '') { 
  103. // Return all messages if no code specified. 
  104. if ( empty($code) ) { 
  105. $all_messages = array(); 
  106. foreach ( (array) $this->errors as $code => $messages ) 
  107. $all_messages = array_merge($all_messages, $messages); 
  108.  
  109. return $all_messages; 
  110.  
  111. if ( isset($this->errors[$code]) ) 
  112. return $this->errors[$code]; 
  113. else 
  114. return array(); 
  115.  
  116. /** 
  117. * Get single error message. 
  118. * 
  119. * This will get the first message available for the code. If no code is 
  120. * given then the first code available will be used. 
  121. * 
  122. * @since 2.1.0 
  123. * 
  124. * @param string|int $code Optional. Error code to retrieve message. 
  125. * @return string 
  126. */ 
  127. public function get_error_message($code = '') { 
  128. if ( empty($code) ) 
  129. $code = $this->get_error_code(); 
  130. $messages = $this->get_error_messages($code); 
  131. if ( empty($messages) ) 
  132. return ''; 
  133. return $messages[0]; 
  134.  
  135. /** 
  136. * Retrieve error data for error code. 
  137. * 
  138. * @since 2.1.0 
  139. * 
  140. * @param string|int $code Optional. Error code. 
  141. * @return mixed Error data, if it exists. 
  142. */ 
  143. public function get_error_data($code = '') { 
  144. if ( empty($code) ) 
  145. $code = $this->get_error_code(); 
  146.  
  147. if ( isset($this->error_data[$code]) ) 
  148. return $this->error_data[$code]; 
  149.  
  150. /** 
  151. * Add an error or append additional message to an existing error. 
  152. * 
  153. * @since 2.1.0 
  154. * @access public 
  155. * 
  156. * @param string|int $code Error code. 
  157. * @param string $message Error message. 
  158. * @param mixed $data Optional. Error data. 
  159. */ 
  160. public function add($code, $message, $data = '') { 
  161. $this->errors[$code][] = $message; 
  162. if ( ! empty($data) ) 
  163. $this->error_data[$code] = $data; 
  164.  
  165. /** 
  166. * Add data for error code. 
  167. * 
  168. * The error code can only contain one error data. 
  169. * 
  170. * @since 2.1.0 
  171. * 
  172. * @param mixed $data Error data. 
  173. * @param string|int $code Error code. 
  174. */ 
  175. public function add_data($data, $code = '') { 
  176. if ( empty($code) ) 
  177. $code = $this->get_error_code(); 
  178.  
  179. $this->error_data[$code] = $data; 
  180.  
  181. /** 
  182. * Removes the specified error. 
  183. * 
  184. * This function removes all error messages associated with the specified 
  185. * error code, along with any error data for that code. 
  186. * 
  187. * @since 4.1.0 
  188. * 
  189. * @param string|int $code Error code. 
  190. */ 
  191. public function remove( $code ) { 
  192. unset( $this->errors[ $code ] ); 
  193. unset( $this->error_data[ $code ] ); 
  194.  
  195. /** 
  196. * Check whether variable is a WordPress Error. 
  197. * 
  198. * Returns true if $thing is an object of the WP_Error class. 
  199. * 
  200. * @since 2.1.0 
  201. * 
  202. * @param mixed $thing Check if unknown variable is a WP_Error object. 
  203. * @return bool True, if WP_Error. False, if not WP_Error. 
  204. */ 
  205. function is_wp_error( $thing ) { 
  206. return ( $thing instanceof WP_Error ); 
.