diff options
Diffstat (limited to 'includes/Message.php')
| -rw-r--r-- | includes/Message.php | 464 |
1 files changed, 322 insertions, 142 deletions
diff --git a/includes/Message.php b/includes/Message.php index 57c6264d..4df0d809 100644 --- a/includes/Message.php +++ b/includes/Message.php @@ -157,9 +157,12 @@ * @since 1.17 */ class Message { + /** * In which language to get this message. True, which is the default, * means the current interface language, false content language. + * + * @var bool */ protected $interface = true; @@ -172,12 +175,18 @@ class Message { protected $language = null; /** - * The message key. + * @var string The message key. If $keysToTry has more than one element, + * this may change to one of the keys to try when fetching the message text. */ protected $key; /** - * List of parameters which will be substituted into the message. + * @var string[] List of keys to try when fetching the message. + */ + protected $keysToTry; + + /** + * @var array List of parameters which will be substituted into the message. */ protected $parameters = array(); @@ -189,21 +198,23 @@ class Message { * * block-parse * * parse (default) * * plain + * + * @var string */ protected $format = 'parse'; /** - * Whether database can be used. + * @var bool Whether database can be used. */ protected $useDatabase = true; /** - * Title object to use as context + * @var Title Title object to use as context. */ protected $title = null; /** - * Content object representing the message + * @var Content Content object representing the message. */ protected $content = null; @@ -213,49 +224,82 @@ class Message { protected $message; /** - * Constructor. * @since 1.17 - * @param $key: message key, or array of message keys to try and use the first non-empty message for - * @param array $params message parameters - * @return Message: $this + * + * @param string|string[] $key Message key or array of message keys to try and use the first + * non-empty message for. + * @param array $params Message parameters. + * @param Language $language Optional language of the message, defaults to $wgLang. + * + * @throws InvalidArgumentException */ - public function __construct( $key, $params = array() ) { + public function __construct( $key, $params = array(), Language $language = null ) { global $wgLang; - $this->key = $key; + + if ( !is_string( $key ) && !is_array( $key ) ) { + throw new InvalidArgumentException( '$key must be a string or an array' ); + } + + $this->keysToTry = (array)$key; + + if ( empty( $this->keysToTry ) ) { + throw new InvalidArgumentException( '$key must not be an empty list' ); + } + + $this->key = reset( $this->keysToTry ); + $this->parameters = array_values( $params ); - $this->language = $wgLang; + $this->language = $language ? $language : $wgLang; + } + + /** + * @since 1.24 + * + * @return bool True if this is a multi-key message, that is, if the key provided to the + * constructor was a fallback list of keys to try. + */ + public function isMultiKey() { + return count( $this->keysToTry ) > 1; + } + + /** + * @since 1.24 + * + * @return string[] The list of keys to try when fetching the message text, + * in order of preference. + */ + public function getKeysToTry() { + return $this->keysToTry; } /** - * Returns the message key + * Returns the message key. + * + * If a list of multiple possible keys was supplied to the constructor, this method may + * return any of these keys. After the message ahs been fetched, this method will return + * the key that was actually used to fetch the message. * * @since 1.21 * * @return string */ public function getKey() { - if ( is_array( $this->key ) ) { - // May happen if some kind of fallback is applied. - // For now, just use the first key. We really need a better solution. - return $this->key[0]; - } else { - return $this->key; - } + return $this->key; } /** - * Returns the message parameters + * Returns the message parameters. * * @since 1.21 * - * @return string[] + * @return array */ public function getParams() { return $this->parameters; } /** - * Returns the message format + * Returns the message format. * * @since 1.21 * @@ -266,13 +310,27 @@ class Message { } /** + * Returns the Language of the Message. + * + * @since 1.23 + * + * @return Language + */ + public function getLanguage() { + return $this->language; + } + + /** * Factory function that is just wrapper for the real constructor. It is * intended to be used instead of the real constructor, because it allows * chaining method calls, while new objects don't. + * * @since 1.17 - * @param string $key message key - * @param Varargs: parameters as Strings - * @return Message: $this + * + * @param string|string[] $key Message key or array of keys. + * @param mixed $param,... Parameters as strings. + * + * @return Message */ public static function newFromKey( $key /*...*/ ) { $params = func_get_args(); @@ -284,9 +342,13 @@ class Message { * Factory function accepting multiple message keys and returning a message instance * for the first message which is non-empty. If all messages are empty then an * instance of the first message key is returned. + * * @since 1.18 - * @param Varargs: message keys (or first arg as an array of all the message keys) - * @return Message: $this + * + * @param string|string[] $keys,... Message keys, or first argument as an array of all the + * message keys. + * + * @return Message */ public static function newFallbackSequence( /*...*/ ) { $keys = func_get_args(); @@ -304,9 +366,13 @@ class Message { /** * Adds parameters to the parameter list of this message. + * * @since 1.17 - * @param Varargs: parameters as Strings, or a single argument that is an array of Strings - * @return Message: $this + * + * @param mixed $params,... Parameters as strings, or a single argument that is + * an array of strings. + * + * @return Message $this */ public function params( /*...*/ ) { $args = func_get_args(); @@ -323,9 +389,13 @@ class Message { * In other words the parsing process cannot access the contents * of this type of parameter, and you need to make sure it is * sanitized beforehand. The parser will see "$n", instead. + * * @since 1.17 - * @param Varargs: raw parameters as Strings (or single argument that is an array of raw parameters) - * @return Message: $this + * + * @param mixed $params,... Raw parameters as strings, or a single argument that is + * an array of raw parameters. + * + * @return Message $this */ public function rawParams( /*...*/ ) { $params = func_get_args(); @@ -341,9 +411,13 @@ class Message { /** * Add parameters that are numeric and will be passed through * Language::formatNum before substitution + * * @since 1.18 - * @param Varargs: numeric parameters (or single argument that is array of numeric parameters) - * @return Message: $this + * + * @param mixed $param,... Numeric parameters, or a single argument that is + * an array of numeric parameters. + * + * @return Message $this */ public function numParams( /*...*/ ) { $params = func_get_args(); @@ -359,9 +433,13 @@ class Message { /** * Add parameters that are durations of time and will be passed through * Language::formatDuration before substitution + * * @since 1.22 - * @param Varargs: numeric parameters (or single argument that is array of numeric parameters) - * @return Message: $this + * + * @param int|int[] $param,... Duration parameters, or a single argument that is + * an array of duration parameters. + * + * @return Message $this */ public function durationParams( /*...*/ ) { $params = func_get_args(); @@ -377,9 +455,13 @@ class Message { /** * Add parameters that are expiration times and will be passed through * Language::formatExpiry before substitution + * * @since 1.22 - * @param Varargs: numeric parameters (or single argument that is array of numeric parameters) - * @return Message: $this + * + * @param string|string[] $param,... Expiry parameters, or a single argument that is + * an array of expiry parameters. + * + * @return Message $this */ public function expiryParams( /*...*/ ) { $params = func_get_args(); @@ -395,9 +477,13 @@ class Message { /** * Add parameters that are time periods and will be passed through * Language::formatTimePeriod before substitution + * * @since 1.22 - * @param Varargs: numeric parameters (or single argument that is array of numeric parameters) - * @return Message: $this + * + * @param int|int[] $param,... Time period parameters, or a single argument that is + * an array of time period parameters. + * + * @return Message $this */ public function timeperiodParams( /*...*/ ) { $params = func_get_args(); @@ -413,9 +499,13 @@ class Message { /** * Add parameters that are file sizes and will be passed through * Language::formatSize before substitution + * * @since 1.22 - * @param Varargs: numeric parameters (or single argument that is array of numeric parameters) - * @return Message: $this + * + * @param int|int[] $param,... Size parameters, or a single argument that is + * an array of size parameters. + * + * @return Message $this */ public function sizeParams( /*...*/ ) { $params = func_get_args(); @@ -431,9 +521,13 @@ class Message { /** * Add parameters that are bitrates and will be passed through * Language::formatBitrate before substitution + * * @since 1.22 - * @param Varargs: numeric parameters (or single argument that is array of numeric parameters) - * @return Message: $this + * + * @param int|int[] $param,... Bit rate parameters, or a single argument that is + * an array of bit rate parameters. + * + * @return Message $this */ public function bitrateParams( /*...*/ ) { $params = func_get_args(); @@ -448,9 +542,12 @@ class Message { /** * Set the language and the title from a context object + * * @since 1.19 - * @param $context IContextSource - * @return Message: $this + * + * @param IContextSource $context + * + * @return Message $this */ public function setContext( IContextSource $context ) { $this->inLanguage( $context->getLanguage() ); @@ -464,10 +561,13 @@ class Message { * Request the message in any language that is supported. * As a side effect interface message status is unconditionally * turned off. + * * @since 1.17 - * @param $lang Mixed: language code or Language object. + * + * @param Language|string $lang Language code or Language object. + * + * @return Message $this * @throws MWException - * @return Message: $this */ public function inLanguage( $lang ) { if ( $lang instanceof Language || $lang instanceof StubUserLang ) { @@ -482,6 +582,7 @@ class Message { . "passed a String or Language object; $type given" ); } + $this->message = null; $this->interface = false; return $this; } @@ -489,9 +590,11 @@ class Message { /** * Request the message in the wiki's content language, * unless it is disabled for this message. + * * @since 1.17 * @see $wgForceUIMsgAsContentMsg - * @return Message: $this + * + * @return Message $this */ public function inContentLanguage() { global $wgForceUIMsgAsContentMsg; @@ -500,39 +603,47 @@ class Message { } global $wgContLang; - $this->interface = false; - $this->language = $wgContLang; + $this->inLanguage( $wgContLang ); return $this; } /** * Allows manipulating the interface message flag directly. * Can be used to restore the flag after setting a language. - * @param $value bool - * @return Message: $this + * * @since 1.20 + * + * @param bool $interface + * + * @return Message $this */ - public function setInterfaceMessageFlag( $value ) { - $this->interface = (bool)$value; + public function setInterfaceMessageFlag( $interface ) { + $this->interface = (bool)$interface; return $this; } /** * Enable or disable database use. + * * @since 1.17 - * @param $value Boolean - * @return Message: $this + * + * @param bool $useDatabase + * + * @return Message $this */ - public function useDatabase( $value ) { - $this->useDatabase = (bool)$value; + public function useDatabase( $useDatabase ) { + $this->useDatabase = (bool)$useDatabase; return $this; } /** * Set the Title object to use as context when transforming the message + * * @since 1.18 - * @param $title Title object - * @return Message: $this + * + * @param Title $title + * + * @return Message $this */ public function title( $title ) { $this->title = $title; @@ -541,6 +652,7 @@ class Message { /** * Returns the message as a Content object. + * * @return Content */ public function content() { @@ -553,14 +665,16 @@ class Message { /** * Returns the message parsed from wikitext to HTML. + * * @since 1.17 - * @return String: HTML + * + * @return string HTML */ public function toString() { $string = $this->fetchMessage(); if ( $string === false ) { - $key = htmlspecialchars( is_array( $this->key ) ? $this->key[0] : $this->key ); + $key = htmlspecialchars( $this->key ); if ( $this->format === 'plain' ) { return '<' . $key . '>'; } @@ -582,10 +696,7 @@ class Message { # Maybe transform using the full parser if ( $this->format === 'parse' ) { $string = $this->parseText( $string ); - $m = array(); - if ( preg_match( '/^<p>(.*)\n?<\/p>\n?$/sU', $string, $m ) ) { - $string = $m[1]; - } + $string = Parser::stripOuterParagraph( $string ); } elseif ( $this->format === 'block-parse' ) { $string = $this->parseText( $string ); } elseif ( $this->format === 'text' ) { @@ -605,8 +716,10 @@ class Message { * Magic method implementation of the above (for PHP >= 5.2.0), so we can do, eg: * $foo = Message::get( $key ); * $string = "<abbr>$foo</abbr>"; + * * @since 1.18 - * @return String + * + * @return string */ public function __toString() { // PHP doesn't allow __toString to throw exceptions and will @@ -630,9 +743,11 @@ class Message { } /** - * Fully parse the text from wikitext to HTML + * Fully parse the text from wikitext to HTML. + * * @since 1.17 - * @return String parsed HTML + * + * @return string Parsed HTML. */ public function parse() { $this->format = 'parse'; @@ -641,8 +756,10 @@ class Message { /** * Returns the message text. {{-transformation is done. + * * @since 1.17 - * @return String: Unescaped message text. + * + * @return string Unescaped message text. */ public function text() { $this->format = 'text'; @@ -651,8 +768,10 @@ class Message { /** * Returns the message text as-is, only parameters are substituted. + * * @since 1.17 - * @return String: Unescaped untransformed message text. + * + * @return string Unescaped untransformed message text. */ public function plain() { $this->format = 'plain'; @@ -661,8 +780,10 @@ class Message { /** * Returns the parsed message text which is always surrounded by a block element. + * * @since 1.17 - * @return String: HTML + * + * @return string HTML */ public function parseAsBlock() { $this->format = 'block-parse'; @@ -672,8 +793,10 @@ class Message { /** * Returns the message text. {{-transformation is done and the result * is escaped excluding any raw parameters. + * * @since 1.17 - * @return String: Escaped message text. + * + * @return string Escaped message text. */ public function escaped() { $this->format = 'escaped'; @@ -682,8 +805,10 @@ class Message { /** * Check whether a message key has been defined currently. + * * @since 1.17 - * @return Bool: true if it is and false if not. + * + * @return bool */ public function exists() { return $this->fetchMessage() !== false; @@ -691,9 +816,11 @@ class Message { /** * Check whether a message does not exist, or is an empty string + * * @since 1.18 - * @return Bool: true if is is and false if not * @todo FIXME: Merge with isDisabled()? + * + * @return bool */ public function isBlank() { $message = $this->fetchMessage(); @@ -701,9 +828,11 @@ class Message { } /** - * Check whether a message does not exist, is an empty string, or is "-" + * Check whether a message does not exist, is an empty string, or is "-". + * * @since 1.18 - * @return Bool: true if it is and false if not + * + * @return bool */ public function isDisabled() { $message = $this->fetchMessage(); @@ -712,73 +841,90 @@ class Message { /** * @since 1.17 - * @param $value - * @return array + * + * @param mixed $raw + * + * @return array Array with a single "raw" key. */ - public static function rawParam( $value ) { - return array( 'raw' => $value ); + public static function rawParam( $raw ) { + return array( 'raw' => $raw ); } /** * @since 1.18 - * @param $value - * @return array + * + * @param mixed $num + * + * @return array Array with a single "num" key. */ - public static function numParam( $value ) { - return array( 'num' => $value ); + public static function numParam( $num ) { + return array( 'num' => $num ); } /** * @since 1.22 - * @param $value - * @return array + * + * @param int $duration + * + * @return int[] Array with a single "duration" key. */ - public static function durationParam( $value ) { - return array( 'duration' => $value ); + public static function durationParam( $duration ) { + return array( 'duration' => $duration ); } /** * @since 1.22 - * @param $value - * @return array + * + * @param string $expiry + * + * @return string[] Array with a single "expiry" key. */ - public static function expiryParam( $value ) { - return array( 'expiry' => $value ); + public static function expiryParam( $expiry ) { + return array( 'expiry' => $expiry ); } /** * @since 1.22 - * @param $value - * @return array + * + * @param number $period + * + * @return number[] Array with a single "period" key. */ - public static function timeperiodParam( $value ) { - return array( 'period' => $value ); + public static function timeperiodParam( $period ) { + return array( 'period' => $period ); } /** * @since 1.22 - * @param $value - * @return array + * + * @param int $size + * + * @return int[] Array with a single "size" key. */ - public static function sizeParam( $value ) { - return array( 'size' => $value ); + public static function sizeParam( $size ) { + return array( 'size' => $size ); } /** * @since 1.22 - * @param $value - * @return array + * + * @param int $bitrate + * + * @return int[] Array with a single "bitrate" key. */ - public static function bitrateParam( $value ) { - return array( 'bitrate' => $value ); + public static function bitrateParam( $bitrate ) { + return array( 'bitrate' => $bitrate ); } /** * Substitutes any parameters into the message text. + * * @since 1.17 - * @param string $message the message text - * @param string $type either before or after - * @return String + * + * @param string $message The message text. + * @param string $type Either "before" or "after". + * + * @return string */ protected function replaceParameters( $message, $type = 'before' ) { $replacementKeys = array(); @@ -794,9 +940,12 @@ class Message { /** * Extracts the parameter type and preprocessed the value if needed. + * * @since 1.18 - * @param string|array $param Parameter as defined in this class. - * @return Tuple(type, value) + * + * @param mixed $param Parameter as defined in this class. + * + * @return array Array with the parameter type (either "before" or "after") and the value. */ protected function extractParam( $param ) { if ( is_array( $param ) ) { @@ -817,10 +966,12 @@ class Message { } elseif ( isset( $param['bitrate'] ) ) { return array( 'before', $this->language->formatBitrate( $param['bitrate'] ) ); } else { - trigger_error( - "Invalid message parameter: " . htmlspecialchars( serialize( $param ) ), - E_USER_WARNING - ); + $warning = 'Invalid parameter for message "' . $this->getKey() . '": ' . + htmlspecialchars( serialize( $param ) ); + trigger_error( $warning, E_USER_WARNING ); + $e = new Exception; + wfDebugLog( 'Bug58676', $warning . "\n" . $e->getTraceAsString() ); + return array( 'before', '[INVALID]' ); } } elseif ( $param instanceof Message ) { @@ -835,48 +986,66 @@ class Message { /** * Wrapper for what ever method we use to parse wikitext. + * * @since 1.17 - * @param string $string Wikitext message contents - * @return string Wikitext parsed into HTML + * + * @param string $string Wikitext message contents. + * + * @return string Wikitext parsed into HTML. */ protected function parseText( $string ) { - $out = MessageCache::singleton()->parse( $string, $this->title, /*linestart*/true, $this->interface, $this->language ); - return is_object( $out ) ? $out->getText() : $out; + $out = MessageCache::singleton()->parse( + $string, + $this->title, + /*linestart*/true, + $this->interface, + $this->language + ); + + return $out instanceof ParserOutput ? $out->getText() : $out; } /** * Wrapper for what ever method we use to {{-transform wikitext. + * * @since 1.17 - * @param string $string Wikitext message contents + * + * @param string $string Wikitext message contents. + * * @return string Wikitext with {{-constructs replaced with their values. */ protected function transformText( $string ) { - return MessageCache::singleton()->transform( $string, $this->interface, $this->language, $this->title ); + return MessageCache::singleton()->transform( + $string, + $this->interface, + $this->language, + $this->title + ); } /** - * Wrapper for what ever method we use to get message contents + * Wrapper for what ever method we use to get message contents. + * * @since 1.17 - * @throws MWException + * * @return string + * @throws MWException If message key array is empty. */ protected function fetchMessage() { - if ( !isset( $this->message ) ) { + if ( $this->message === null ) { $cache = MessageCache::singleton(); - if ( is_array( $this->key ) ) { - if ( !count( $this->key ) ) { - throw new MWException( "Given empty message key array." ); - } - foreach ( $this->key as $key ) { - $message = $cache->get( $key, $this->useDatabase, $this->language ); - if ( $message !== false && $message !== '' ) { - break; - } + + foreach ( $this->keysToTry as $key ) { + $message = $cache->get( $key, $this->useDatabase, $this->language ); + if ( $message !== false && $message !== '' ) { + break; } - $this->message = $message; - } else { - $this->message = $cache->get( $this->key, $this->useDatabase, $this->language ); } + + // NOTE: The constructor makes sure keysToTry isn't empty, + // so we know that $key and $message are initialized. + $this->key = $key; + $this->message = $message; } return $this->message; } @@ -897,18 +1066,27 @@ class Message { * @since 1.21 */ class RawMessage extends Message { + /** * Call the parent constructor, then store the key as * the message. * - * @param string $key Message to use - * @param array $params Parameters for the message * @see Message::__construct + * + * @param string $text Message to use. + * @param array $params Parameters for the message. + * + * @throws InvalidArgumentException */ - public function __construct( $key, $params = array() ) { - parent::__construct( $key, $params ); + public function __construct( $text, $params = array() ) { + if ( !is_string( $text ) ) { + throw new InvalidArgumentException( '$text must be a string' ); + } + + parent::__construct( $text, $params ); + // The key is the message. - $this->message = $key; + $this->message = $text; } /** @@ -918,9 +1096,11 @@ class RawMessage extends Message { */ public function fetchMessage() { // Just in case the message is unset somewhere. - if ( !isset( $this->message ) ) { + if ( $this->message === null ) { $this->message = $this->key; } + return $this->message; } + } |