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.
40 class Status
extends StatusValue
{
42 public $cleanCallback = false;
45 * Succinct helper method to wrap a StatusValue
47 * This is is useful when formatting StatusValue objects:
49 * $this->getOutput()->addHtml( Status::wrap( $sv )->getHTML() );
52 * @param StatusValue|Status $sv
55 public static function wrap( $sv ) {
56 if ( $sv instanceof static ) {
60 $result = new static();
61 $result->ok
=& $sv->ok
;
62 $result->errors
=& $sv->errors
;
63 $result->value
=& $sv->value
;
64 $result->successCount
=& $sv->successCount
;
65 $result->failCount
=& $sv->failCount
;
66 $result->success
=& $sv->success
;
72 * Backwards compatibility logic
76 * @throws RuntimeException
78 function __get( $name ) {
79 if ( $name === 'ok' ) {
81 } elseif ( $name === 'errors' ) {
82 return $this->getErrors();
85 throw new RuntimeException( "Cannot get '$name' property." );
89 * Change operation result
90 * Backwards compatibility logic
94 * @throws RuntimeException
96 function __set( $name, $value ) {
97 if ( $name === 'ok' ) {
98 $this->setOK( $value );
99 } elseif ( !property_exists( $this, $name ) ) {
100 // Caller is using undeclared ad-hoc properties
101 $this->$name = $value;
103 throw new RuntimeException( "Cannot set '$name' property." );
108 * Splits this Status object into two new Status objects, one which contains only
109 * the error messages, and one that contains the warnings, only. The returned array is
112 * 0 => object(Status) # the Status with error messages, only
113 * 1 => object(Status) # The Status with warning messages, only
118 public function splitByErrorType() {
119 list( $errorsOnlyStatus, $warningsOnlyStatus ) = parent
::splitByErrorType();
120 $errorsOnlyStatus->cleanCallback
=
121 $warningsOnlyStatus->cleanCallback
= $this->cleanCallback
;
123 return [ $errorsOnlyStatus, $warningsOnlyStatus ];
127 * Returns the wrapped StatusValue object
128 * @return StatusValue
131 public function getStatusValue() {
136 * @param array $params
139 protected function cleanParams( array $params ) {
140 if ( !$this->cleanCallback
) {
144 foreach ( $params as $i => $param ) {
145 $cleanParams[$i] = call_user_func( $this->cleanCallback
, $param );
151 * @param string|Language|null $lang Language to use for processing
152 * messages, or null to default to the user language.
155 protected function languageFromParam( $lang ) {
156 if ( $lang === null ) {
157 return RequestContext
::getMain()->getLanguage();
158 } elseif ( $lang instanceof Language
) {
161 return Language
::factory( $lang );
166 * Get the error list as a wikitext formatted list
168 * @param string|bool $shortContext A short enclosing context message name, to
169 * be used when there is a single error
170 * @param string|bool $longContext A long enclosing context message name, for a list
171 * @param string|Language $lang Language to use for processing messages
174 public function getWikiText( $shortContext = false, $longContext = false, $lang = null ) {
175 $lang = $this->languageFromParam( $lang );
177 $rawErrors = $this->getErrors();
178 if ( count( $rawErrors ) == 0 ) {
179 if ( $this->isOK() ) {
180 $this->fatal( 'internalerror_info',
181 __METHOD__
. " called for a good result, this is incorrect\n" );
183 $this->fatal( 'internalerror_info',
184 __METHOD__
. ": Invalid result object: no error text but not OK\n" );
186 $rawErrors = $this->getErrors(); // just added a fatal
188 if ( count( $rawErrors ) == 1 ) {
189 $s = $this->getErrorMessage( $rawErrors[0], $lang )->plain();
190 if ( $shortContext ) {
191 $s = wfMessage( $shortContext, $s )->inLanguage( $lang )->plain();
192 } elseif ( $longContext ) {
193 $s = wfMessage( $longContext, "* $s\n" )->inLanguage( $lang )->plain();
196 $errors = $this->getErrorMessageArray( $rawErrors, $lang );
197 foreach ( $errors as &$error ) {
198 $error = $error->plain();
200 $s = '* ' . implode( "\n* ", $errors ) . "\n";
201 if ( $longContext ) {
202 $s = wfMessage( $longContext, $s )->inLanguage( $lang )->plain();
203 } elseif ( $shortContext ) {
204 $s = wfMessage( $shortContext, "\n$s\n" )->inLanguage( $lang )->plain();
211 * Get a bullet list of the errors as a Message object.
213 * $shortContext and $longContext can be used to wrap the error list in some text.
214 * $shortContext will be preferred when there is a single error; $longContext will be
215 * preferred when there are multiple ones. In either case, $1 will be replaced with
216 * the list of errors.
218 * $shortContext is assumed to use $1 as an inline parameter: if there is a single item,
219 * it will not be made into a list; if there are multiple items, newlines will be inserted
221 * $longContext is assumed to use $1 as a standalone parameter; it will always receive a list.
223 * If both parameters are missing, and there is only one error, no bullet will be added.
225 * @param string|string[]|bool $shortContext A message name or an array of message names.
226 * @param string|string[]|bool $longContext A message name or an array of message names.
227 * @param string|Language $lang Language to use for processing messages
230 public function getMessage( $shortContext = false, $longContext = false, $lang = null ) {
231 $lang = $this->languageFromParam( $lang );
233 $rawErrors = $this->getErrors();
234 if ( count( $rawErrors ) == 0 ) {
235 if ( $this->isOK() ) {
236 $this->fatal( 'internalerror_info',
237 __METHOD__
. " called for a good result, this is incorrect\n" );
239 $this->fatal( 'internalerror_info',
240 __METHOD__
. ": Invalid result object: no error text but not OK\n" );
242 $rawErrors = $this->getErrors(); // just added a fatal
244 if ( count( $rawErrors ) == 1 ) {
245 $s = $this->getErrorMessage( $rawErrors[0], $lang );
246 if ( $shortContext ) {
247 $s = wfMessage( $shortContext, $s )->inLanguage( $lang );
248 } elseif ( $longContext ) {
249 $wrapper = new RawMessage( "* \$1\n" );
250 $wrapper->params( $s )->parse();
251 $s = wfMessage( $longContext, $wrapper )->inLanguage( $lang );
254 $msgs = $this->getErrorMessageArray( $rawErrors, $lang );
255 $msgCount = count( $msgs );
257 $s = new RawMessage( '* $' . implode( "\n* \$", range( 1, $msgCount ) ) );
258 $s->params( $msgs )->parse();
260 if ( $longContext ) {
261 $s = wfMessage( $longContext, $s )->inLanguage( $lang );
262 } elseif ( $shortContext ) {
263 $wrapper = new RawMessage( "\n\$1\n", [ $s ] );
265 $s = wfMessage( $shortContext, $wrapper )->inLanguage( $lang );
273 * Return the message for a single error
275 * The code string can be used a message key with per-language versions.
276 * If $error is an array, the "params" field is a list of parameters for the message.
278 * @param array|string $error Code string or (key: code string, params: string[]) map
279 * @param string|Language $lang Language to use for processing messages
282 protected function getErrorMessage( $error, $lang = null ) {
283 if ( is_array( $error ) ) {
284 if ( isset( $error['message'] ) && $error['message'] instanceof Message
) {
285 $msg = $error['message'];
286 } elseif ( isset( $error['message'] ) && isset( $error['params'] ) ) {
287 $msg = wfMessage( $error['message'],
288 array_map( 'wfEscapeWikiText', $this->cleanParams( $error['params'] ) ) );
290 $msgName = array_shift( $error );
291 $msg = wfMessage( $msgName,
292 array_map( 'wfEscapeWikiText', $this->cleanParams( $error ) ) );
294 } elseif ( is_string( $error ) ) {
295 $msg = wfMessage( $error );
297 throw new UnexpectedValueException( "Got " . get_class( $error ) . " for key." );
300 $msg->inLanguage( $this->languageFromParam( $lang ) );
305 * Get the error message as HTML. This is done by parsing the wikitext error message
306 * @param string|bool $shortContext A short enclosing context message name, to
307 * be used when there is a single error
308 * @param string|bool $longContext A long enclosing context message name, for a list
309 * @param string|Language|null $lang Language to use for processing messages
312 public function getHTML( $shortContext = false, $longContext = false, $lang = null ) {
313 $lang = $this->languageFromParam( $lang );
314 $text = $this->getWikiText( $shortContext, $longContext, $lang );
315 $out = MessageCache
::singleton()->parse( $text, null, true, true, $lang );
316 return $out instanceof ParserOutput ?
$out->getText() : $out;
320 * Return an array with a Message object for each error.
321 * @param array $errors
322 * @param string|Language $lang Language to use for processing messages
325 protected function getErrorMessageArray( $errors, $lang = null ) {
326 $lang = $this->languageFromParam( $lang );
327 return array_map( function ( $e ) use ( $lang ) {
328 return $this->getErrorMessage( $e, $lang );
333 * Get the list of errors (but not warnings)
335 * @return array A list in which each entry is an array with a message key as its first element.
336 * The remaining array elements are the message parameters.
337 * @deprecated since 1.25
339 public function getErrorsArray() {
340 return $this->getStatusArray( 'error' );
344 * Get the list of warnings (but not errors)
346 * @return array A list in which each entry is an array with a message key as its first element.
347 * The remaining array elements are the message parameters.
348 * @deprecated since 1.25
350 public function getWarningsArray() {
351 return $this->getStatusArray( 'warning' );
355 * Returns a list of status messages of the given type (or all if false)
357 * @note: this handles RawMessage poorly
359 * @param string|bool $type
362 protected function getStatusArray( $type = false ) {
365 foreach ( $this->getErrors() as $error ) {
366 if ( $type === false ||
$error['type'] === $type ) {
367 if ( $error['message'] instanceof MessageSpecifier
) {
368 $result[] = array_merge(
369 [ $error['message']->getKey() ],
370 $error['message']->getParams()
372 } elseif ( $error['params'] ) {
373 $result[] = array_merge( [ $error['message'] ], $error['params'] );
375 $result[] = [ $error['message'] ];
384 * Don't save the callback when serializing, because Closures can't be
385 * serialized and we're going to clear it in __wakeup anyway.
388 $keys = array_keys( get_object_vars( $this ) );
389 return array_diff( $keys, [ 'cleanCallback' ] );
393 * Sanitize the callback parameter on wakeup, to avoid arbitrary execution.
395 function __wakeup() {
396 $this->cleanCallback
= false;