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
{
41 /** @var callable|false */
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' ) {
82 if ( $name === 'errors' ) {
83 return $this->getErrors();
86 throw new RuntimeException( "Cannot get '$name' property." );
90 * Change operation result
91 * Backwards compatibility logic
95 * @throws RuntimeException
97 function __set( $name, $value ) {
98 if ( $name === 'ok' ) {
99 $this->setOK( $value );
100 } elseif ( !property_exists( $this, $name ) ) {
101 // Caller is using undeclared ad-hoc properties
102 $this->$name = $value;
104 throw new RuntimeException( "Cannot set '$name' property." );
109 * Splits this Status object into two new Status objects, one which contains only
110 * the error messages, and one that contains the warnings, only. The returned array is
113 * 0 => object(Status) # The Status with error messages, only
114 * 1 => object(Status) # The Status with warning messages, only
119 public function splitByErrorType() {
120 list( $errorsOnlyStatus, $warningsOnlyStatus ) = parent
::splitByErrorType();
121 $errorsOnlyStatus->cleanCallback
=
122 $warningsOnlyStatus->cleanCallback
= $this->cleanCallback
;
124 return [ $errorsOnlyStatus, $warningsOnlyStatus ];
128 * Returns the wrapped StatusValue object
129 * @return StatusValue
132 public function getStatusValue() {
137 * @param array $params
140 protected function cleanParams( array $params ) {
141 if ( !$this->cleanCallback
) {
145 foreach ( $params as $i => $param ) {
146 $cleanParams[$i] = call_user_func( $this->cleanCallback
, $param );
152 * @param string|Language|null|StubUserLang $lang Language to use for processing
153 * messages, or null to default to the user language.
154 * @return Language|StubUserLang
156 protected function languageFromParam( $lang ) {
157 if ( $lang === null ) {
158 return RequestContext
::getMain()->getLanguage();
160 if ( $lang instanceof Language ||
$lang instanceof StubUserLang
) {
163 return Language
::factory( $lang );
167 * Get the error list as a wikitext formatted list
169 * @param string|bool $shortContext A short enclosing context message name, to
170 * be used when there is a single error
171 * @param string|bool $longContext A long enclosing context message name, for a list
172 * @param string|Language|null|StubUserLang $lang Language to use for processing messages
175 public function getWikiText( $shortContext = false, $longContext = false, $lang = null ) {
176 $lang = $this->languageFromParam( $lang );
178 $rawErrors = $this->getErrors();
179 if ( count( $rawErrors ) === 0 ) {
180 if ( $this->isOK() ) {
181 $this->fatal( 'internalerror_info',
182 __METHOD__
. " called for a good result, this is incorrect\n" );
184 $this->fatal( 'internalerror_info',
185 __METHOD__
. ": Invalid result object: no error text but not OK\n" );
187 $rawErrors = $this->getErrors(); // just added a fatal
189 if ( count( $rawErrors ) === 1 ) {
190 $s = $this->getErrorMessage( $rawErrors[0], $lang )->plain();
191 if ( $shortContext ) {
192 $s = wfMessage( $shortContext, $s )->inLanguage( $lang )->plain();
193 } elseif ( $longContext ) {
194 $s = wfMessage( $longContext, "* $s\n" )->inLanguage( $lang )->plain();
197 $errors = $this->getErrorMessageArray( $rawErrors, $lang );
198 foreach ( $errors as &$error ) {
199 $error = $error->plain();
201 $s = '* ' . implode( "\n* ", $errors ) . "\n";
202 if ( $longContext ) {
203 $s = wfMessage( $longContext, $s )->inLanguage( $lang )->plain();
204 } elseif ( $shortContext ) {
205 $s = wfMessage( $shortContext, "\n$s\n" )->inLanguage( $lang )->plain();
212 * Get a bullet list of the errors as a Message object.
214 * $shortContext and $longContext can be used to wrap the error list in some text.
215 * $shortContext will be preferred when there is a single error; $longContext will be
216 * preferred when there are multiple ones. In either case, $1 will be replaced with
217 * the list of errors.
219 * $shortContext is assumed to use $1 as an inline parameter: if there is a single item,
220 * it will not be made into a list; if there are multiple items, newlines will be inserted
222 * $longContext is assumed to use $1 as a standalone parameter; it will always receive a list.
224 * If both parameters are missing, and there is only one error, no bullet will be added.
226 * @param string|string[]|bool $shortContext A message name or an array of message names.
227 * @param string|string[]|bool $longContext A message name or an array of message names.
228 * @param string|Language|null $lang Language to use for processing messages
231 public function getMessage( $shortContext = false, $longContext = false, $lang = null ) {
232 $lang = $this->languageFromParam( $lang );
234 $rawErrors = $this->getErrors();
235 if ( count( $rawErrors ) === 0 ) {
236 if ( $this->isOK() ) {
237 $this->fatal( 'internalerror_info',
238 __METHOD__
. " called for a good result, this is incorrect\n" );
240 $this->fatal( 'internalerror_info',
241 __METHOD__
. ": Invalid result object: no error text but not OK\n" );
243 $rawErrors = $this->getErrors(); // just added a fatal
245 if ( count( $rawErrors ) === 1 ) {
246 $s = $this->getErrorMessage( $rawErrors[0], $lang );
247 if ( $shortContext ) {
248 $s = wfMessage( $shortContext, $s )->inLanguage( $lang );
249 } elseif ( $longContext ) {
250 $wrapper = new RawMessage( "* \$1\n" );
251 $wrapper->params( $s )->parse();
252 $s = wfMessage( $longContext, $wrapper )->inLanguage( $lang );
255 $msgs = $this->getErrorMessageArray( $rawErrors, $lang );
256 $msgCount = count( $msgs );
258 $s = new RawMessage( '* $' . implode( "\n* \$", range( 1, $msgCount ) ) );
259 $s->params( $msgs )->parse();
261 if ( $longContext ) {
262 $s = wfMessage( $longContext, $s )->inLanguage( $lang );
263 } elseif ( $shortContext ) {
264 $wrapper = new RawMessage( "\n\$1\n", [ $s ] );
266 $s = wfMessage( $shortContext, $wrapper )->inLanguage( $lang );
274 * Return the message for a single error
276 * The code string can be used a message key with per-language versions.
277 * If $error is an array, the "params" field is a list of parameters for the message.
279 * @param array|string $error Code string or (key: code string, params: string[]) map
280 * @param string|Language|null $lang Language to use for processing messages
283 protected function getErrorMessage( $error, $lang = null ) {
284 if ( is_array( $error ) ) {
285 if ( isset( $error['message'] ) && $error['message'] instanceof Message
) {
286 $msg = $error['message'];
287 } elseif ( isset( $error['message'] ) && isset( $error['params'] ) ) {
288 $msg = wfMessage( $error['message'],
289 array_map( 'wfEscapeWikiText', $this->cleanParams( $error['params'] ) ) );
291 $msgName = array_shift( $error );
292 $msg = wfMessage( $msgName,
293 array_map( 'wfEscapeWikiText', $this->cleanParams( $error ) ) );
295 } elseif ( is_string( $error ) ) {
296 $msg = wfMessage( $error );
298 throw new UnexpectedValueException( 'Got ' . get_class( $error ) . ' for key.' );
301 $msg->inLanguage( $this->languageFromParam( $lang ) );
306 * Get the error message as HTML. This is done by parsing the wikitext error message
307 * @param string|bool $shortContext A short enclosing context message name, to
308 * be used when there is a single error
309 * @param string|bool $longContext A long enclosing context message name, for a list
310 * @param string|Language|null $lang Language to use for processing messages
313 public function getHTML( $shortContext = false, $longContext = false, $lang = null ) {
314 $lang = $this->languageFromParam( $lang );
315 $text = $this->getWikiText( $shortContext, $longContext, $lang );
316 $out = MessageCache
::singleton()->parse( $text, null, true, true, $lang );
317 return $out instanceof ParserOutput
318 ?
$out->getText( [ 'enableSectionEditLinks' => false ] )
323 * Return an array with a Message object for each error.
324 * @param array $errors
325 * @param string|Language|null $lang Language to use for processing messages
328 protected function getErrorMessageArray( $errors, $lang = null ) {
329 $lang = $this->languageFromParam( $lang );
330 return array_map( function ( $e ) use ( $lang ) {
331 return $this->getErrorMessage( $e, $lang );
336 * Get the list of errors (but not warnings)
338 * @return array A list in which each entry is an array with a message key as its first element.
339 * The remaining array elements are the message parameters.
340 * @deprecated since 1.25
342 public function getErrorsArray() {
343 return $this->getStatusArray( 'error' );
347 * Get the list of warnings (but not errors)
349 * @return array A list in which each entry is an array with a message key as its first element.
350 * The remaining array elements are the message parameters.
351 * @deprecated since 1.25
353 public function getWarningsArray() {
354 return $this->getStatusArray( 'warning' );
358 * Returns a list of status messages of the given type (or all if false)
360 * @note this handles RawMessage poorly
362 * @param string|bool $type
365 protected function getStatusArray( $type = false ) {
368 foreach ( $this->getErrors() as $error ) {
369 if ( $type === false ||
$error['type'] === $type ) {
370 if ( $error['message'] instanceof MessageSpecifier
) {
371 $result[] = array_merge(
372 [ $error['message']->getKey() ],
373 $error['message']->getParams()
375 } elseif ( $error['params'] ) {
376 $result[] = array_merge( [ $error['message'] ], $error['params'] );
378 $result[] = [ $error['message'] ];
387 * Don't save the callback when serializing, because Closures can't be
388 * serialized and we're going to clear it in __wakeup anyway.
392 $keys = array_keys( get_object_vars( $this ) );
393 return array_diff( $keys, [ 'cleanCallback' ] );
397 * Sanitize the callback parameter on wakeup, to avoid arbitrary execution.
399 function __wakeup() {
400 $this->cleanCallback
= false;