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] )->plain();
192 if ( $shortContext ) {
193 $s = wfMessage( $shortContext, $s )->plain();
194 } elseif ( $longContext ) {
195 $s = wfMessage( $longContext, "* $s\n" )->plain();
198 $errors = $this->getErrorMessageArray( $this->errors
);
199 foreach ( $errors as &$error ) {
200 $error = $error->plain();
202 $s = '* ' . implode( "\n* ", $errors ) . "\n";
203 if ( $longContext ) {
204 $s = wfMessage( $longContext, $s )->plain();
205 } elseif ( $shortContext ) {
206 $s = wfMessage( $shortContext, "\n$s\n" )->plain();
213 * Get the error list as a Message object
215 * @param string $shortContext a short enclosing context message name, to
216 * be used when there is a single error
217 * @param string $longContext a long enclosing context message name, for a list
220 function getMessage( $shortContext = false, $longContext = false ) {
221 if ( count( $this->errors
) == 0 ) {
223 $this->fatal( 'internalerror_info',
224 __METHOD__
. " called for a good result, this is incorrect\n" );
226 $this->fatal( 'internalerror_info',
227 __METHOD__
. ": Invalid result object: no error text but not OK\n" );
230 if ( count( $this->errors
) == 1 ) {
231 $s = $this->getErrorMessage( $this->errors
[0] );
232 if ( $shortContext ) {
233 $s = wfMessage( $shortContext, $s );
234 } elseif ( $longContext ) {
235 $wrapper = new RawMessage( "* \$1\n" );
236 $wrapper->params( $s )->parse();
237 $s = wfMessage( $longContext, $wrapper );
240 $msgs = $this->getErrorMessageArray( $this->errors
);
241 $msgCount = count( $msgs );
243 if ( $shortContext ) {
247 $wrapper = new RawMessage( '* $' . implode( "\n* \$", range( 1, $msgCount ) ) );
248 $s = $wrapper->params( $msgs )->parse();
250 if ( $longContext ) {
251 $s = wfMessage( $longContext, $wrapper );
252 } elseif ( $shortContext ) {
253 $wrapper = new RawMessage( "\n\$1\n", $wrapper );
255 $s = wfMessage( $shortContext, $wrapper );
263 * Return the message for a single error.
264 * @param $error Mixed With an array & two values keyed by
265 * 'message' and 'params', use those keys-value pairs.
266 * Otherwise, if its an array, just use the first value as the
267 * message and the remaining items as the params.
271 protected function getErrorMessage( $error ) {
272 if ( is_array( $error ) ) {
273 if ( isset( $error['message'] ) && $error['message'] instanceof Message
) {
274 $msg = $error['message'];
275 } elseif ( isset( $error['message'] ) && isset( $error['params'] ) ) {
276 $msg = wfMessage( $error['message'],
277 array_map( 'wfEscapeWikiText', $this->cleanParams( $error['params'] ) ) );
279 $msgName = array_shift( $error );
280 $msg = wfMessage( $msgName,
281 array_map( 'wfEscapeWikiText', $this->cleanParams( $error ) ) );
284 $msg = wfMessage( $error );
290 * Get the error message as HTML. This is done by parsing the wikitext error
293 * @note: this does not perform a full wikitext to HTML conversion, it merely applies
294 * a message transformation.
295 * @todo figure out whether that is actually The Right Thing.
297 public function getHTML( $shortContext = false, $longContext = false ) {
298 $text = $this->getWikiText( $shortContext, $longContext );
299 return MessageCache
::singleton()->transform( $text, true );
303 * Return an array with the wikitext for each item in the array.
304 * @param $errors Array
307 protected function getErrorMessageArray( $errors ) {
308 return array_map( array( $this, 'getErrorMessage' ), $errors );
312 * Merge another status object into this one
314 * @param $other Status Other Status object
315 * @param $overwriteValue Boolean: whether to override the "value" member
317 function merge( $other, $overwriteValue = false ) {
318 $this->errors
= array_merge( $this->errors
, $other->errors
);
319 $this->ok
= $this->ok
&& $other->ok
;
320 if ( $overwriteValue ) {
321 $this->value
= $other->value
;
323 $this->successCount +
= $other->successCount
;
324 $this->failCount +
= $other->failCount
;
328 * Get the list of errors (but not warnings)
330 * @return array A list in which each entry is an array with a message key as its first element.
331 * The remaining array elements are the message parameters.
333 function getErrorsArray() {
334 return $this->getStatusArray( "error" );
338 * Get the list of warnings (but not errors)
340 * @return array A list in which each entry is an array with a message key as its first element.
341 * The remaining array elements are the message parameters.
343 function getWarningsArray() {
344 return $this->getStatusArray( "warning" );
348 * Returns a list of status messages of the given type
349 * @param $type String
353 protected function getStatusArray( $type ) {
355 foreach ( $this->errors
as $error ) {
356 if ( $error['type'] === $type ) {
357 if ( $error['message'] instanceof Message
) {
358 $result[] = array_merge( array( $error['message']->getKey() ), $error['message']->getParams() );
359 } elseif ( $error['params'] ) {
360 $result[] = array_merge( array( $error['message'] ), $error['params'] );
362 $result[] = array( $error['message'] );
370 * Returns a list of status messages of the given type, with message and
371 * params left untouched, like a sane version of getStatusArray
373 * @param $type String
377 public function getErrorsByType( $type ) {
379 foreach ( $this->errors
as $error ) {
380 if ( $error['type'] === $type ) {
388 * Returns true if the specified message is present as a warning or error
390 * Note, due to the lack of tools for comparing Message objects, this
391 * function will not work when using a Message object as a parameter.
393 * @param string $msg message name
396 function hasMessage( $msg ) {
397 foreach ( $this->errors
as $error ) {
398 if ( $error['message'] === $msg ) {
406 * If the specified source message exists, replace it with the specified
407 * destination message, but keep the same parameters as in the original error.
409 * Note, due to the lack of tools for comparing Message objects, this
410 * function will not work when using a Message object as the search parameter.
412 * @param $source Message|String: Message key or object to search for
413 * @param $dest Message|String: Replacement message key or object
414 * @return bool Return true if the replacement was done, false otherwise.
416 function replaceMessage( $source, $dest ) {
418 foreach ( $this->errors
as $index => $error ) {
419 if ( $error['message'] === $source ) {
420 $this->errors
[$index]['message'] = $dest;
430 public function getValue() {