3 * Generic operation result.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * Generic operation result class
25 * Has warning/error list, boolean status and arbitrary value
27 * "Good" means the operation was completed with no warnings or errors.
29 * "OK" means the operation was partially or wholly completed.
31 * An operation which is not OK should have errors so that the user can be
32 * informed as to what went wrong. Calling the fatal() function sets an error
33 * message and simultaneously switches off the OK flag.
35 * The recommended pattern for Status objects is to return a Status object
36 * unconditionally, i.e. both on success and on failure -- so that the
37 * developer of the calling code is reminded that the function can fail, and
38 * so that a lack of error-handling will be explicit.
44 /** Counters for batch operations */
45 public $successCount = 0, $failCount = 0;
46 /** Array to indicate which items of the batch operations were successful */
47 public $success = array();
49 /*semi-private*/ var $errors = array();
50 /*semi-private*/ var $cleanCallback = false;
53 * Factory function for fatal errors
55 * @param string|Message $message message name or object
58 static function newFatal( $message /*, parameters...*/ ) {
59 $params = func_get_args();
61 call_user_func_array( array( &$result, 'error' ), $params );
67 * Factory function for good results
72 static function newGood( $value = null ) {
74 $result->value
= $value;
79 * Change operation result
81 * @param $ok Boolean: whether the operation completed
84 function setResult( $ok, $value = null ) {
86 $this->value
= $value;
90 * Returns whether the operation completed and didn't have any error or
96 return $this->ok
&& !$this->errors
;
100 * Returns whether the operation completed
111 * @param string|Message $message message name or object
113 function warning( $message /*, parameters... */ ) {
114 $params = array_slice( func_get_args(), 1 );
115 $this->errors
[] = array(
117 'message' => $message,
118 'params' => $params );
122 * Add an error, do not set fatal flag
123 * This can be used for non-fatal errors
125 * @param string|Message $message message name or object
127 function error( $message /*, parameters... */ ) {
128 $params = array_slice( func_get_args(), 1 );
129 $this->errors
[] = array(
131 'message' => $message,
132 'params' => $params );
136 * Add an error and set OK to false, indicating that the operation
137 * as a whole was fatal
139 * @param string|Message $message message name or object
141 function fatal( $message /*, parameters... */ ) {
142 $params = array_slice( func_get_args(), 1 );
143 $this->errors
[] = array(
145 'message' => $message,
146 'params' => $params );
151 * Sanitize the callback parameter on wakeup, to avoid arbitrary execution.
153 function __wakeup() {
154 $this->cleanCallback
= false;
158 * @param $params array
161 protected function cleanParams( $params ) {
162 if ( !$this->cleanCallback
) {
165 $cleanParams = array();
166 foreach ( $params as $i => $param ) {
167 $cleanParams[$i] = call_user_func( $this->cleanCallback
, $param );
173 * Get the error list as a wikitext formatted list
175 * @param string $shortContext a short enclosing context message name, to
176 * be used when there is a single error
177 * @param string $longContext a long enclosing context message name, for a list
180 function getWikiText( $shortContext = false, $longContext = false ) {
181 if ( count( $this->errors
) == 0 ) {
183 $this->fatal( 'internalerror_info',
184 __METHOD__
. " called for a good result, this is incorrect\n" );
186 $this->fatal( 'internalerror_info',
187 __METHOD__
. ": Invalid result object: no error text but not OK\n" );
190 if ( count( $this->errors
) == 1 ) {
191 $s = $this->getErrorMessage( $this->errors
[0] );
192 if ( $shortContext ) {
193 $s = wfMessage( $shortContext, $s )->plain();
194 } elseif ( $longContext ) {
195 $s = wfMessage( $longContext, "* $s\n" )->plain();
198 $s = '* ' . implode( "\n* ",
199 $this->getErrorMessageArray( $this->errors
) ) . "\n";
200 if ( $longContext ) {
201 $s = wfMessage( $longContext, $s )->plain();
202 } elseif ( $shortContext ) {
203 $s = wfMessage( $shortContext, "\n$s\n" )->plain();
210 * Return the message for a single error.
211 * @param $error Mixed With an array & two values keyed by
212 * 'message' and 'params', use those keys-value pairs.
213 * Otherwise, if its an array, just use the first value as the
214 * message and the remaining items as the params.
218 protected function getErrorMessage( $error ) {
219 if ( is_array( $error ) ) {
220 if ( isset( $error['message'] ) && $error['message'] instanceof Message
) {
221 $msg = $error['message'];
222 } elseif ( isset( $error['message'] ) && isset( $error['params'] ) ) {
223 $msg = wfMessage( $error['message'],
224 array_map( 'wfEscapeWikiText', $this->cleanParams( $error['params'] ) ) );
226 $msgName = array_shift( $error );
227 $msg = wfMessage( $msgName,
228 array_map( 'wfEscapeWikiText', $this->cleanParams( $error ) ) );
231 $msg = wfMessage( $error );
233 return $msg->plain();
237 * Get the error message as HTML. This is done by parsing the wikitext error
240 * @note: this does not perform a full wikitext to HTML conversion, it merely applies
241 * a message transformation.
242 * @todo figure out whether that is actually The Right Thing.
244 public function getHTML( $shortContext = false, $longContext = false ) {
245 $text = $this->getWikiText( $shortContext, $longContext );
246 return MessageCache
::singleton()->transform( $text, true );
250 * Return an array with the wikitext for each item in the array.
251 * @param $errors Array
254 protected function getErrorMessageArray( $errors ) {
255 return array_map( array( $this, 'getErrorMessage' ), $errors );
259 * Merge another status object into this one
261 * @param $other Status Other Status object
262 * @param $overwriteValue Boolean: whether to override the "value" member
264 function merge( $other, $overwriteValue = false ) {
265 $this->errors
= array_merge( $this->errors
, $other->errors
);
266 $this->ok
= $this->ok
&& $other->ok
;
267 if ( $overwriteValue ) {
268 $this->value
= $other->value
;
270 $this->successCount +
= $other->successCount
;
271 $this->failCount +
= $other->failCount
;
275 * Get the list of errors (but not warnings)
277 * @return array A list in which each entry is an array with a message key as its first element.
278 * The remaining array elements are the message parameters.
280 function getErrorsArray() {
281 return $this->getStatusArray( "error" );
285 * Get the list of warnings (but not errors)
287 * @return array A list in which each entry is an array with a message key as its first element.
288 * The remaining array elements are the message parameters.
290 function getWarningsArray() {
291 return $this->getStatusArray( "warning" );
295 * Returns a list of status messages of the given type
296 * @param $type String
300 protected function getStatusArray( $type ) {
302 foreach ( $this->errors
as $error ) {
303 if ( $error['type'] === $type ) {
304 if ( $error['message'] instanceof Message
) {
305 $result[] = array_merge( array( $error['message']->getKey() ), $error['message']->getParams() );
306 } elseif ( $error['params'] ) {
307 $result[] = array_merge( array( $error['message'] ), $error['params'] );
309 $result[] = array( $error['message'] );
317 * Returns a list of status messages of the given type, with message and
318 * params left untouched, like a sane version of getStatusArray
320 * @param $type String
324 public function getErrorsByType( $type ) {
326 foreach ( $this->errors
as $error ) {
327 if ( $error['type'] === $type ) {
335 * Returns true if the specified message is present as a warning or error
337 * Note, due to the lack of tools for comparing Message objects, this
338 * function will not work when using a Message object as a parameter.
340 * @param string $msg message name
343 function hasMessage( $msg ) {
344 foreach ( $this->errors
as $error ) {
345 if ( $error['message'] === $msg ) {
353 * If the specified source message exists, replace it with the specified
354 * destination message, but keep the same parameters as in the original error.
356 * Note, due to the lack of tools for comparing Message objects, this
357 * function will not work when using a Message object as the search parameter.
359 * @param $source Message|String: Message key or object to search for
360 * @param $dest Message|String: Replacement message key or object
361 * @return bool Return true if the replacement was done, false otherwise.
363 function replaceMessage( $source, $dest ) {
365 foreach ( $this->errors
as $index => $error ) {
366 if ( $error['message'] === $source ) {
367 $this->errors
[$index]['message'] = $dest;
375 * Backward compatibility function for WikiError -> Status migration
379 public function getMessage() {
380 return $this->getWikiText();
386 public function getValue() {