summaryrefslogtreecommitdiff
path: root/includes/Message.php
diff options
context:
space:
mode:
authorPierre Schmitz <pierre@archlinux.de>2014-12-27 15:41:37 +0100
committerPierre Schmitz <pierre@archlinux.de>2014-12-31 11:43:28 +0100
commitc1f9b1f7b1b77776192048005dcc66dcf3df2bfb (patch)
tree2b38796e738dd74cb42ecd9bfd151803108386bc /includes/Message.php
parentb88ab0086858470dd1f644e64cb4e4f62bb2be9b (diff)
Update to MediaWiki 1.24.1
Diffstat (limited to 'includes/Message.php')
-rw-r--r--includes/Message.php464
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;
}
+
}