df4cbf5ac6
get_debug_type() does the same thing but better (spelling type names in the same way as in type declarations, and including names of object classes and resource types). It was added in PHP 8, but the symfony/polyfill-php80 package provides it while we still support 7.4. Also remove uses of get_class() and get_resource_type() where the new method already provides the same information. For reference: https://www.php.net/manual/en/function.get-debug-type.php https://www.php.net/manual/en/function.gettype.php In this commit I'm only changing code where it looks like the result is used only for some king of debug, log, or test output. This probably won't break anything important, but I'm not sure whether anything might depend on the exact values. Change-Id: I7c1f0a8f669228643e86f8e511c0e26a2edb2948
597 lines
17 KiB
PHP
597 lines
17 KiB
PHP
<?php
|
|
/**
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program; if not, write to the Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
* http://www.gnu.org/copyleft/gpl.html
|
|
*
|
|
* @file
|
|
*/
|
|
|
|
use MediaWiki\Message\Converter;
|
|
use MediaWiki\Message\Message;
|
|
use Wikimedia\Assert\Assert;
|
|
use Wikimedia\Message\MessageSpecifier;
|
|
use Wikimedia\Message\MessageValue;
|
|
|
|
/**
|
|
* Generic operation result class
|
|
* Has warning/error list, boolean status and arbitrary value
|
|
*
|
|
* "Good" means the operation was completed with no warnings or errors.
|
|
*
|
|
* "OK" means the operation was partially or wholly completed.
|
|
*
|
|
* An operation which is not OK should have errors so that the user can be
|
|
* informed as to what went wrong. Calling the fatal() function sets an error
|
|
* message and simultaneously switches off the OK flag.
|
|
*
|
|
* The recommended pattern for Status objects is to return a StatusValue
|
|
* unconditionally, i.e. both on success and on failure -- so that the
|
|
* developer of the calling code is reminded that the function can fail, and
|
|
* so that a lack of error-handling will be explicit.
|
|
*
|
|
* The use of Message objects should be avoided when serializability is needed.
|
|
*
|
|
* @newable
|
|
* @stable to extend
|
|
* @since 1.25
|
|
*/
|
|
class StatusValue implements Stringable {
|
|
|
|
/**
|
|
* @var bool
|
|
* @internal Only for use by Status. Use {@link self::isOK()} or {@link self::setOK()}.
|
|
*/
|
|
protected $ok = true;
|
|
|
|
/**
|
|
* @var array[]
|
|
* @internal Only for use by Status. Use {@link self::getErrors()} (get full list),
|
|
* {@link self::splitByErrorType()} (get errors/warnings), or
|
|
* {@link self::fatal()}, {@link self::error()} or {@link self::warning()} (add error/warning).
|
|
*/
|
|
protected $errors = [];
|
|
|
|
/** @var mixed */
|
|
public $value;
|
|
|
|
/** @var bool[] Map of (key => bool) to indicate success of each part of batch operations */
|
|
public $success = [];
|
|
|
|
/** @var int Counter for batch operations */
|
|
public $successCount = 0;
|
|
|
|
/** @var int Counter for batch operations */
|
|
public $failCount = 0;
|
|
|
|
/** @var mixed arbitrary extra data about the operation */
|
|
public $statusData;
|
|
|
|
/**
|
|
* Factory function for fatal errors
|
|
*
|
|
* @param string|MessageSpecifier $message Message key or object
|
|
* @param mixed ...$parameters
|
|
* @return static
|
|
*/
|
|
public static function newFatal( $message, ...$parameters ) {
|
|
$result = new static();
|
|
$result->fatal( $message, ...$parameters );
|
|
return $result;
|
|
}
|
|
|
|
/**
|
|
* Factory function for good results
|
|
*
|
|
* @param mixed|null $value
|
|
* @return static
|
|
*/
|
|
public static function newGood( $value = null ) {
|
|
$result = new static();
|
|
$result->value = $value;
|
|
return $result;
|
|
}
|
|
|
|
/**
|
|
* Splits this StatusValue object into two new StatusValue objects, one which contains only
|
|
* the error messages, and one that contains the warnings, only. The returned array is
|
|
* defined as:
|
|
* [
|
|
* 0 => object(StatusValue) # the StatusValue with error messages, only
|
|
* 1 => object(StatusValue) # The StatusValue with warning messages, only
|
|
* ]
|
|
*
|
|
* @return static[]
|
|
*/
|
|
public function splitByErrorType() {
|
|
$errorsOnlyStatusValue = static::newGood();
|
|
$warningsOnlyStatusValue = static::newGood();
|
|
$warningsOnlyStatusValue->setResult( true, $this->getValue() );
|
|
$errorsOnlyStatusValue->setResult( $this->isOK(), $this->getValue() );
|
|
|
|
foreach ( $this->errors as $item ) {
|
|
if ( $item['type'] === 'warning' ) {
|
|
$warningsOnlyStatusValue->errors[] = $item;
|
|
} else {
|
|
$errorsOnlyStatusValue->errors[] = $item;
|
|
}
|
|
}
|
|
|
|
return [ $errorsOnlyStatusValue, $warningsOnlyStatusValue ];
|
|
}
|
|
|
|
/**
|
|
* Returns whether the operation completed and didn't have any error or
|
|
* warnings
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isGood() {
|
|
return $this->ok && !$this->errors;
|
|
}
|
|
|
|
/**
|
|
* Returns whether the operation completed
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isOK() {
|
|
return $this->ok;
|
|
}
|
|
|
|
/**
|
|
* @return mixed
|
|
*/
|
|
public function getValue() {
|
|
return $this->value;
|
|
}
|
|
|
|
/**
|
|
* Get the list of errors
|
|
*
|
|
* Each error is a (message:string or MessageSpecifier,params:array) map
|
|
*
|
|
* @deprecated since 1.43 Use `->getMessages()` instead
|
|
* @return array[]
|
|
* @phan-return array{type:'warning'|'error', message:string|MessageSpecifier, params:array}[]
|
|
*/
|
|
public function getErrors() {
|
|
return $this->errors;
|
|
}
|
|
|
|
/**
|
|
* Change operation status
|
|
*
|
|
* @param bool $ok
|
|
* @return $this
|
|
*/
|
|
public function setOK( $ok ) {
|
|
$this->ok = $ok;
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Change operation result
|
|
*
|
|
* @param bool $ok Whether the operation completed
|
|
* @param mixed|null $value
|
|
* @return $this
|
|
*/
|
|
public function setResult( $ok, $value = null ) {
|
|
$this->ok = (bool)$ok;
|
|
$this->value = $value;
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Add a new error to the error array ($this->errors) if that error is not already in the
|
|
* error array. Each error is passed as an array with the following fields:
|
|
*
|
|
* - type: 'error' or 'warning'
|
|
* - message: a string (message key) or MessageSpecifier
|
|
* - params: an array of string parameters
|
|
*
|
|
* If the new error is of type 'error' and it matches an existing error of type 'warning',
|
|
* the existing error is upgraded to type 'error'. An error provided as a MessageSpecifier
|
|
* will successfully match an error provided as the same string message key and array of
|
|
* parameters as separate array elements.
|
|
*
|
|
* @param array $newError
|
|
* @phan-param array{type:'warning'|'error', message:string|MessageSpecifier, params:array} $newError
|
|
* @return $this
|
|
*/
|
|
private function addError( array $newError ) {
|
|
[ 'type' => $newType, 'message' => $newKey, 'params' => $newParams ] = $newError;
|
|
if ( $newKey instanceof MessageSpecifier ) {
|
|
if ( $newParams ) {
|
|
// Deprecate code like `Status::newFatal( wfMessage( 'foo' ), 'param' )`
|
|
// - the parameters have always been ignored, so this is usually a mistake.
|
|
wfDeprecatedMsg( 'Combining MessageSpecifier and parameters array' .
|
|
' was deprecated in MediaWiki 1.43', '1.43' );
|
|
}
|
|
$newParams = $newKey->getParams();
|
|
$newKey = $newKey->getKey();
|
|
}
|
|
|
|
foreach ( $this->errors as [ 'type' => &$type, 'message' => $key, 'params' => $params ] ) {
|
|
if ( $key instanceof MessageSpecifier ) {
|
|
$params = $key->getParams();
|
|
$key = $key->getKey();
|
|
}
|
|
if ( $newKey === $key && $newParams === $params ) {
|
|
if ( $type === 'warning' && $newType === 'error' ) {
|
|
$type = 'error';
|
|
}
|
|
return $this;
|
|
}
|
|
}
|
|
|
|
$this->errors[] = $newError;
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Add a new warning
|
|
*
|
|
* @param string|MessageSpecifier|MessageValue $message Message key or object
|
|
* @param mixed ...$parameters
|
|
* @return $this
|
|
*/
|
|
public function warning( $message, ...$parameters ) {
|
|
$message = $this->normalizeMessage( $message );
|
|
|
|
return $this->addError( [
|
|
'type' => 'warning',
|
|
'message' => $message,
|
|
'params' => $parameters
|
|
] );
|
|
}
|
|
|
|
/**
|
|
* Add an error, do not set fatal flag
|
|
* This can be used for non-fatal errors
|
|
*
|
|
* @param string|MessageSpecifier|MessageValue $message Message key or object
|
|
* @param mixed ...$parameters
|
|
* @return $this
|
|
*/
|
|
public function error( $message, ...$parameters ) {
|
|
$message = $this->normalizeMessage( $message );
|
|
|
|
return $this->addError( [
|
|
'type' => 'error',
|
|
'message' => $message,
|
|
'params' => $parameters
|
|
] );
|
|
}
|
|
|
|
/**
|
|
* Add an error and set OK to false, indicating that the operation
|
|
* as a whole was fatal
|
|
*
|
|
* @param string|MessageSpecifier|MessageValue $message Message key or object
|
|
* @param mixed ...$parameters
|
|
* @return $this
|
|
*/
|
|
public function fatal( $message, ...$parameters ) {
|
|
$this->ok = false;
|
|
return $this->error( $message, ...$parameters );
|
|
}
|
|
|
|
/**
|
|
* Merge another status object into this one
|
|
*
|
|
* @param StatusValue $other
|
|
* @param bool $overwriteValue Whether to override the "value" member
|
|
* @return $this
|
|
*/
|
|
public function merge( $other, $overwriteValue = false ) {
|
|
if ( $this->statusData !== null && $other->statusData !== null ) {
|
|
throw new RuntimeException( "Status cannot be merged, because they both have \$statusData" );
|
|
} else {
|
|
$this->statusData ??= $other->statusData;
|
|
}
|
|
|
|
foreach ( $other->errors as $error ) {
|
|
$this->addError( $error );
|
|
}
|
|
$this->ok = $this->ok && $other->ok;
|
|
if ( $overwriteValue ) {
|
|
$this->value = $other->value;
|
|
}
|
|
$this->successCount += $other->successCount;
|
|
$this->failCount += $other->failCount;
|
|
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Returns a list of status messages of the given type
|
|
*
|
|
* Each entry is a map of:
|
|
* - message: string message key or MessageSpecifier
|
|
* - params: array list of parameters
|
|
*
|
|
* @deprecated since 1.43 Use `->getMessages( $type )` instead
|
|
* @param string $type
|
|
* @return array[]
|
|
* @phan-return array{type:'warning'|'error', message:string|MessageSpecifier, params:array}[]
|
|
*/
|
|
public function getErrorsByType( $type ) {
|
|
$result = [];
|
|
foreach ( $this->errors as $error ) {
|
|
if ( $error['type'] === $type ) {
|
|
$result[] = $error;
|
|
}
|
|
}
|
|
|
|
return $result;
|
|
}
|
|
|
|
/**
|
|
* Returns a list of error messages, optionally only those of the given type
|
|
*
|
|
* @since 1.43
|
|
* @param ?string $type If provided, only return messages of the type 'warning' or 'error'
|
|
* @phan-param null|'warning'|'error' $type
|
|
* @return MessageSpecifier[]
|
|
*/
|
|
public function getMessages( ?string $type = null ): array {
|
|
Assert::parameter( $type === null || $type === 'warning' || $type === 'error',
|
|
'$type', "must be null, 'warning', or 'error'" );
|
|
$result = [];
|
|
foreach ( $this->errors as $error ) {
|
|
if ( $type === null || $error['type'] === $type ) {
|
|
[ 'message' => $key, 'params' => $params ] = $error;
|
|
if ( $key instanceof MessageSpecifier ) {
|
|
$result[] = $key;
|
|
} else {
|
|
// TODO: Make MessageValue implement MessageSpecifier, and use a MessageValue here
|
|
$result[] = new Message( $key, $params );
|
|
}
|
|
}
|
|
}
|
|
|
|
return $result;
|
|
}
|
|
|
|
/**
|
|
* Returns true if the specified message is present as a warning or error.
|
|
* Any message using the same key will be found (ignoring the message parameters).
|
|
*
|
|
* @param string $message Message key to search for
|
|
* (this parameter used to allow MessageSpecifier|MessageValue too, deprecated since 1.43)
|
|
* @return bool
|
|
*/
|
|
public function hasMessage( $message ) {
|
|
if ( $message instanceof MessageSpecifier ) {
|
|
wfDeprecatedMsg( 'Passing MessageSpecifier to hasMessage()' .
|
|
' was deprecated in MediaWiki 1.43', '1.43' );
|
|
$message = $message->getKey();
|
|
} elseif ( $message instanceof MessageValue ) {
|
|
wfDeprecatedMsg( 'Passing MessageValue to hasMessage()' .
|
|
' was deprecated in MediaWiki 1.43', '1.43' );
|
|
$message = $message->getKey();
|
|
}
|
|
|
|
foreach ( $this->errors as [ 'message' => $key ] ) {
|
|
if ( ( $key instanceof MessageSpecifier && $key->getKey() === $message ) ||
|
|
$key === $message
|
|
) {
|
|
return true;
|
|
}
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Returns true if any other message than the specified ones is present as a warning or error.
|
|
* Any messages using the same keys will be found (ignoring the message parameters).
|
|
*
|
|
* @param string ...$messages Message keys to search for
|
|
* (this parameter used to allow MessageSpecifier|MessageValue too, deprecated since 1.43)
|
|
* @return bool
|
|
*/
|
|
public function hasMessagesExcept( ...$messages ) {
|
|
$exceptedKeys = [];
|
|
foreach ( $messages as $message ) {
|
|
if ( $message instanceof MessageSpecifier ) {
|
|
wfDeprecatedMsg( 'Passing MessageSpecifier to hasMessagesExcept()' .
|
|
' was deprecated in MediaWiki 1.43', '1.43' );
|
|
$message = $message->getKey();
|
|
} elseif ( $message instanceof MessageValue ) {
|
|
wfDeprecatedMsg( 'Passing MessageValue to hasMessagesExcept()' .
|
|
' was deprecated in MediaWiki 1.43', '1.43' );
|
|
$message = $message->getKey();
|
|
}
|
|
$exceptedKeys[] = $message;
|
|
}
|
|
|
|
foreach ( $this->errors as [ 'message' => $key ] ) {
|
|
if ( $key instanceof MessageSpecifier ) {
|
|
$key = $key->getKey();
|
|
}
|
|
if ( !in_array( $key, $exceptedKeys, true ) ) {
|
|
return true;
|
|
}
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* If the specified source message exists, replace it with the specified
|
|
* destination message, but keep the same parameters as in the original error.
|
|
*
|
|
* When using a string as the `$source` parameter, any message using the same key will be replaced
|
|
* (regardless of whether it was stored as string or as MessageSpecifier, and ignoring the
|
|
* message parameters).
|
|
*
|
|
* When using a MessageValue as the `$source` parameter, this function does not work. This is a
|
|
* bug, but it's impractical to fix. Therefore, passing a MessageValue is deprecated (since 1.43).
|
|
*
|
|
* When using a MessageSpecifier as the `$source` parameter, the message will only be replaced
|
|
* when the same MessageSpecifier object was stored in the StatusValue (compared with `===`).
|
|
* Since the only reliable way to obtain one is to use getErrors(), which is deprecated,
|
|
* passing a MessageSpecifier is deprecated as well (since 1.43).
|
|
*
|
|
* @param string $source Message key to search for
|
|
* (this parameter used to allow MessageSpecifier|MessageValue too, deprecated since 1.43)
|
|
* @param MessageSpecifier|MessageValue|string $dest Replacement message key or object
|
|
* @return bool Return true if the replacement was done, false otherwise.
|
|
*/
|
|
public function replaceMessage( $source, $dest ) {
|
|
$replaced = false;
|
|
|
|
if ( $source instanceof MessageSpecifier ) {
|
|
wfDeprecatedMsg( 'Passing MessageSpecifier as $source to replaceMessage()' .
|
|
' was deprecated in MediaWiki 1.43', '1.43' );
|
|
} elseif ( $source instanceof MessageValue ) {
|
|
wfDeprecatedMsg( 'Passing MessageValue as $source to replaceMessage()' .
|
|
' was deprecated in MediaWiki 1.43', '1.43' );
|
|
$source = $this->normalizeMessage( $source );
|
|
}
|
|
|
|
$dest = $this->normalizeMessage( $dest );
|
|
|
|
foreach ( $this->errors as [ 'message' => &$message, 'params' => &$params ] ) {
|
|
if ( $message === $source ||
|
|
( $message instanceof MessageSpecifier && $message->getKey() === $source )
|
|
) {
|
|
$message = $dest;
|
|
if ( $dest instanceof MessageSpecifier ) {
|
|
// 'params' will be ignored now, so remove them from the internal array
|
|
$params = [];
|
|
}
|
|
$replaced = true;
|
|
}
|
|
}
|
|
|
|
return $replaced;
|
|
}
|
|
|
|
/**
|
|
* Returns a string representation of the status for debugging.
|
|
* This is fairly verbose and may change without notice.
|
|
*
|
|
* @return string
|
|
*/
|
|
public function __toString() {
|
|
$status = $this->isOK() ? "OK" : "Error";
|
|
if ( count( $this->errors ) ) {
|
|
$errorcount = "collected " . ( count( $this->errors ) ) . " message(s) on the way";
|
|
} else {
|
|
$errorcount = "no errors detected";
|
|
}
|
|
if ( isset( $this->value ) ) {
|
|
$valstr = get_debug_type( $this->value ) . " value set";
|
|
} else {
|
|
$valstr = "no value set";
|
|
}
|
|
$out = sprintf( "<%s, %s, %s>",
|
|
$status,
|
|
$errorcount,
|
|
$valstr
|
|
);
|
|
if ( count( $this->errors ) > 0 ) {
|
|
$hdr = sprintf( "+-%'-8s-+-%'-25s-+-%'-36s-+\n", "", "", "" );
|
|
$out .= "\n" . $hdr;
|
|
foreach ( $this->errors as [ 'type' => $type, 'message' => $key, 'params' => $params ] ) {
|
|
if ( $key instanceof MessageSpecifier ) {
|
|
$params = $key->getParams();
|
|
$key = $key->getKey();
|
|
}
|
|
|
|
$keyChunks = mb_str_split( $key, 25 );
|
|
$paramsChunks = mb_str_split( $this->flattenParams( $params, " | " ), 36 );
|
|
|
|
// array_map(null,...) is like Python's zip()
|
|
foreach ( array_map( null, [ $type ], $keyChunks, $paramsChunks )
|
|
as [ $typeChunk, $keyChunk, $paramsChunk ]
|
|
) {
|
|
$out .= sprintf( "| %-8s | %-25s | %-36s |\n",
|
|
$typeChunk,
|
|
$keyChunk,
|
|
$paramsChunk
|
|
);
|
|
}
|
|
}
|
|
$out .= $hdr;
|
|
}
|
|
|
|
return $out;
|
|
}
|
|
|
|
/**
|
|
* @param array $params Message parameters
|
|
* @param string $joiner
|
|
*
|
|
* @return string String representation
|
|
*/
|
|
private function flattenParams( array $params, string $joiner = ', ' ): string {
|
|
$ret = [];
|
|
foreach ( $params as $p ) {
|
|
if ( is_array( $p ) ) {
|
|
$r = '[ ' . self::flattenParams( $p ) . ' ]';
|
|
} elseif ( $p instanceof MessageSpecifier ) {
|
|
$r = '{ ' . $p->getKey() . ': ' . self::flattenParams( $p->getParams() ) . ' }';
|
|
} else {
|
|
$r = (string)$p;
|
|
}
|
|
|
|
$ret[] = mb_strlen( $r ) > 100 ? mb_substr( $r, 0, 99 ) . "..." : $r;
|
|
}
|
|
return implode( $joiner, $ret );
|
|
}
|
|
|
|
/**
|
|
* Returns a list of status messages of the given type (or all if false)
|
|
*
|
|
* @internal Only for use by Status.
|
|
*
|
|
* @param string|bool $type
|
|
* @return array[]
|
|
*/
|
|
protected function getStatusArray( $type = false ) {
|
|
$result = [];
|
|
|
|
foreach ( $this->getErrors() as $error ) {
|
|
if ( !$type || $error['type'] === $type ) {
|
|
if ( $error['message'] instanceof MessageSpecifier ) {
|
|
$result[] = [ $error['message']->getKey(), ...$error['message']->getParams() ];
|
|
} else {
|
|
$result[] = [ $error['message'], ...$error['params'] ];
|
|
}
|
|
}
|
|
}
|
|
|
|
return $result;
|
|
}
|
|
|
|
/**
|
|
* @param MessageSpecifier|MessageValue|string $message
|
|
*
|
|
* @return MessageSpecifier|string
|
|
*/
|
|
private function normalizeMessage( $message ) {
|
|
if ( $message instanceof MessageValue ) {
|
|
$converter = new Converter();
|
|
return $converter->convertMessageValue( $message );
|
|
}
|
|
|
|
return $message;
|
|
}
|
|
}
|