Localisation updates from http://translatewiki.net.
[mediawiki.git] / includes / Status.php
blob7ec1b0f68c703a464e672826e9fb3932076bb726
1 <?php
2 /**
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
20 * @file
23 /**
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 class Status {
36 var $ok = true;
37 var $value;
39 /** Counters for batch operations */
40 public $successCount = 0, $failCount = 0;
41 /** Array to indicate which items of the batch operations were successful */
42 public $success = array();
44 /*semi-private*/ var $errors = array();
45 /*semi-private*/ var $cleanCallback = false;
47 /**
48 * Factory function for fatal errors
50 * @param string|Message $message message name or object
51 * @return Status
53 static function newFatal( $message /*, parameters...*/ ) {
54 $params = func_get_args();
55 $result = new self;
56 call_user_func_array( array( &$result, 'error' ), $params );
57 $result->ok = false;
58 return $result;
61 /**
62 * Factory function for good results
64 * @param $value Mixed
65 * @return Status
67 static function newGood( $value = null ) {
68 $result = new self;
69 $result->value = $value;
70 return $result;
73 /**
74 * Change operation result
76 * @param $ok Boolean: whether the operation completed
77 * @param $value Mixed
79 function setResult( $ok, $value = null ) {
80 $this->ok = $ok;
81 $this->value = $value;
84 /**
85 * Returns whether the operation completed and didn't have any error or
86 * warnings
88 * @return Boolean
90 function isGood() {
91 return $this->ok && !$this->errors;
94 /**
95 * Returns whether the operation completed
97 * @return Boolean
99 function isOK() {
100 return $this->ok;
104 * Add a new warning
106 * @param string|Message $message message name or object
108 function warning( $message /*, parameters... */ ) {
109 $params = array_slice( func_get_args(), 1 );
110 $this->errors[] = array(
111 'type' => 'warning',
112 'message' => $message,
113 'params' => $params );
117 * Add an error, do not set fatal flag
118 * This can be used for non-fatal errors
120 * @param string|Message $message message name or object
122 function error( $message /*, parameters... */ ) {
123 $params = array_slice( func_get_args(), 1 );
124 $this->errors[] = array(
125 'type' => 'error',
126 'message' => $message,
127 'params' => $params );
131 * Add an error and set OK to false, indicating that the operation
132 * as a whole was fatal
134 * @param string|Message $message message name or object
136 function fatal( $message /*, parameters... */ ) {
137 $params = array_slice( func_get_args(), 1 );
138 $this->errors[] = array(
139 'type' => 'error',
140 'message' => $message,
141 'params' => $params );
142 $this->ok = false;
146 * Sanitize the callback parameter on wakeup, to avoid arbitrary execution.
148 function __wakeup() {
149 $this->cleanCallback = false;
153 * @param $params array
154 * @return array
156 protected function cleanParams( $params ) {
157 if ( !$this->cleanCallback ) {
158 return $params;
160 $cleanParams = array();
161 foreach ( $params as $i => $param ) {
162 $cleanParams[$i] = call_user_func( $this->cleanCallback, $param );
164 return $cleanParams;
168 * Get the error list as a wikitext formatted list
170 * @param string $shortContext a short enclosing context message name, to
171 * be used when there is a single error
172 * @param string $longContext a long enclosing context message name, for a list
173 * @return String
175 function getWikiText( $shortContext = false, $longContext = false ) {
176 if ( count( $this->errors ) == 0 ) {
177 if ( $this->ok ) {
178 $this->fatal( 'internalerror_info',
179 __METHOD__ . " called for a good result, this is incorrect\n" );
180 } else {
181 $this->fatal( 'internalerror_info',
182 __METHOD__ . ": Invalid result object: no error text but not OK\n" );
185 if ( count( $this->errors ) == 1 ) {
186 $s = $this->getErrorMessage( $this->errors[0] );
187 if ( $shortContext ) {
188 $s = wfMessage( $shortContext, $s )->plain();
189 } elseif ( $longContext ) {
190 $s = wfMessage( $longContext, "* $s\n" )->plain();
192 } else {
193 $s = '* ' . implode( "\n* ",
194 $this->getErrorMessageArray( $this->errors ) ) . "\n";
195 if ( $longContext ) {
196 $s = wfMessage( $longContext, $s )->plain();
197 } elseif ( $shortContext ) {
198 $s = wfMessage( $shortContext, "\n$s\n" )->plain();
201 return $s;
205 * Return the message for a single error.
206 * @param $error Mixed With an array & two values keyed by
207 * 'message' and 'params', use those keys-value pairs.
208 * Otherwise, if its an array, just use the first value as the
209 * message and the remaining items as the params.
211 * @return String
213 protected function getErrorMessage( $error ) {
214 if ( is_array( $error ) ) {
215 if ( isset( $error['message'] ) && $error['message'] instanceof Message ) {
216 $msg = $error['message'];
217 } elseif ( isset( $error['message'] ) && isset( $error['params'] ) ) {
218 $msg = wfMessage( $error['message'],
219 array_map( 'wfEscapeWikiText', $this->cleanParams( $error['params'] ) ) );
220 } else {
221 $msgName = array_shift( $error );
222 $msg = wfMessage( $msgName,
223 array_map( 'wfEscapeWikiText', $this->cleanParams( $error ) ) );
225 } else {
226 $msg = wfMessage( $error );
228 return $msg->plain();
232 * Get the error message as HTML. This is done by parsing the wikitext error
233 * message.
235 * @note: this does not perform a full wikitext to HTML conversion, it merely applies
236 * a message transformation.
237 * @todo figure out whether that is actually The Right Thing.
239 public function getHTML( $shortContext = false, $longContext = false ) {
240 $text = $this->getWikiText( $shortContext, $longContext );
241 return MessageCache::singleton()->transform( $text, true );
245 * Return an array with the wikitext for each item in the array.
246 * @param $errors Array
247 * @return Array
249 protected function getErrorMessageArray( $errors ) {
250 return array_map( array( $this, 'getErrorMessage' ), $errors );
254 * Merge another status object into this one
256 * @param $other Status Other Status object
257 * @param $overwriteValue Boolean: whether to override the "value" member
259 function merge( $other, $overwriteValue = false ) {
260 $this->errors = array_merge( $this->errors, $other->errors );
261 $this->ok = $this->ok && $other->ok;
262 if ( $overwriteValue ) {
263 $this->value = $other->value;
265 $this->successCount += $other->successCount;
266 $this->failCount += $other->failCount;
270 * Get the list of errors (but not warnings)
272 * @return array A list in which each entry is an array with a message key as its first element.
273 * The remaining array elements are the message parameters.
275 function getErrorsArray() {
276 return $this->getStatusArray( "error" );
280 * Get the list of warnings (but not errors)
282 * @return array A list in which each entry is an array with a message key as its first element.
283 * The remaining array elements are the message parameters.
285 function getWarningsArray() {
286 return $this->getStatusArray( "warning" );
290 * Returns a list of status messages of the given type
291 * @param $type String
293 * @return Array
295 protected function getStatusArray( $type ) {
296 $result = array();
297 foreach ( $this->errors as $error ) {
298 if ( $error['type'] === $type ) {
299 if ( $error['message'] instanceof Message ) {
300 $result[] = array_merge( array( $error['message']->getKey() ), $error['message']->getParams() );
301 } elseif ( $error['params'] ) {
302 $result[] = array_merge( array( $error['message'] ), $error['params'] );
303 } else {
304 $result[] = array( $error['message'] );
308 return $result;
312 * Returns a list of status messages of the given type, with message and
313 * params left untouched, like a sane version of getStatusArray
315 * @param $type String
317 * @return Array
319 public function getErrorsByType( $type ) {
320 $result = array();
321 foreach ( $this->errors as $error ) {
322 if ( $error['type'] === $type ) {
323 $result[] = $error;
326 return $result;
330 * Returns true if the specified message is present as a warning or error
332 * Note, due to the lack of tools for comparing Message objects, this
333 * function will not work when using a Message object as a parameter.
335 * @param string $msg message name
336 * @return Boolean
338 function hasMessage( $msg ) {
339 foreach ( $this->errors as $error ) {
340 if ( $error['message'] === $msg ) {
341 return true;
344 return false;
348 * If the specified source message exists, replace it with the specified
349 * destination message, but keep the same parameters as in the original error.
351 * Note, due to the lack of tools for comparing Message objects, this
352 * function will not work when using a Message object as the search parameter.
354 * @param $source Message|String: Message key or object to search for
355 * @param $dest Message|String: Replacement message key or object
356 * @return bool Return true if the replacement was done, false otherwise.
358 function replaceMessage( $source, $dest ) {
359 $replaced = false;
360 foreach ( $this->errors as $index => $error ) {
361 if ( $error['message'] === $source ) {
362 $this->errors[$index]['message'] = $dest;
363 $replaced = true;
366 return $replaced;
370 * Backward compatibility function for WikiError -> Status migration
372 * @return String
374 public function getMessage() {
375 return $this->getWikiText();
379 * @return mixed
381 public function getValue() {
382 return $this->value;