protected $language = null;
/**
- * @var string|string[] The message key or array of keys.
+ * @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;
+ /**
+ * @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.
*/
* 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(), 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 = $language ? $language : $wgLang;
}
/**
- * Returns the message key or the first from an array of message keys.
+ * @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.
+ *
+ * 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;
}
/**
return $this;
}
+ /**
+ * Add parameters that are plaintext and will be passed through without
+ * the content being evaluated. Plaintext parameters are not valid as
+ * arguments to parser functions. This differs from self::rawParams in
+ * that the Message class handles escaping to match the output format.
+ *
+ * @since 1.25
+ *
+ * @param string|string[] $param,... plaintext parameters, or a single argument that is
+ * an array of plaintext parameters.
+ *
+ * @return Message $this
+ */
+ public function plaintextParams( /*...*/ ) {
+ $params = func_get_args();
+ if ( isset( $params[0] ) && is_array( $params[0] ) ) {
+ $params = $params[0];
+ }
+ foreach ( $params as $param ) {
+ $this->parameters[] = self::plaintextParam( $param );
+ }
+ return $this;
+ }
+
/**
* Set the language and the title from a context object
*
$string = $this->fetchMessage();
if ( $string === false ) {
- $key = htmlspecialchars( is_array( $this->key ) ? $this->key[0] : $this->key );
- if ( $this->format === 'plain' ) {
- return '<' . $key . '>';
+ if ( $this->format === 'plain' || $this->format === 'text' ) {
+ return '<' . $this->key . '>';
}
- return '<' . $key . '>';
+ return '<' . htmlspecialchars( $this->key ) . '>';
}
# Replace $* with a list of parameters for &uselang=qqx.
// Doh! Cause a fatal error after all?
}
- if ( $this->format === 'plain' ) {
+ if ( $this->format === 'plain' || $this->format === 'text' ) {
return '<' . $this->key . '>';
}
- return '<' . $this->key . '>';
+ return '<' . htmlspecialchars( $this->key ) . '>';
}
}
return array( 'bitrate' => $bitrate );
}
+ /**
+ * @since 1.25
+ *
+ * @param string $plaintext
+ *
+ * @return string[] Array with a single "plaintext" key.
+ */
+ public static function plaintextParam( $plaintext ) {
+ return array( 'plaintext' => $plaintext );
+ }
+
/**
* Substitutes any parameters into the message text.
*
return array( 'before', $this->language->formatSize( $param['size'] ) );
} elseif ( isset( $param['bitrate'] ) ) {
return array( 'before', $this->language->formatBitrate( $param['bitrate'] ) );
+ } elseif ( isset( $param['plaintext'] ) ) {
+ return array( 'after', $this->formatPlaintext( $param['plaintext'] ) );
} else {
$warning = 'Invalid parameter for message "' . $this->getKey() . '": ' .
htmlspecialchars( serialize( $param ) );
protected function fetchMessage() {
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;
}
+ /**
+ * Formats a message parameter wrapped with 'plaintext'. Ensures that
+ * the entire string is displayed unchanged when displayed in the output
+ * format.
+ *
+ * @since 1.25
+ *
+ * @param string $plaintext String to ensure plaintext output of
+ *
+ * @return string Input plaintext encoded for output to $this->format
+ */
+ protected function formatPlaintext( $plaintext ) {
+ switch ( $this->format ) {
+ case 'text':
+ case 'plain':
+ return $plaintext;
+
+ case 'parse':
+ case 'block-parse':
+ case 'escaped':
+ default:
+ return htmlspecialchars( $plaintext, ENT_QUOTES );
+
+ }
+ }
}
/**
*
* @see Message::__construct
*
- * @param string|string[] $key Message to use.
+ * @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;
}
/**
if ( $this->message === null ) {
$this->message = $this->key;
}
+
return $this->message;
}