namespace Wikimedia\Message;
/**
- * A MessageValue holds a key and an array of parameters
+ * Value object representing a message for i18n.
+ *
+ * A MessageValue holds a key and an array of parameters. It can be converted
+ * to a string in a particular language using formatters obtained from an
+ * IMessageFormatterFactory.
+ *
+ * MessageValues are pure value objects and are safely newable.
*/
class MessageValue {
/** @var string */
/**
* @param string $key
- * @param array $params Each element of the parameter array
- * may be either a MessageParam or a scalar. If it is a scalar, it is
- * converted to a parameter of type TEXT.
+ * @param (MessageParam|MessageValue|string|int|float)[] $params Values that are not instances
+ * of MessageParam are wrapped using ParamType::TEXT.
*/
public function __construct( $key, $params = [] ) {
$this->key = $key;
/**
* Chainable mutator which adds text parameters and MessageParam parameters
*
- * @param mixed ...$values Scalar or MessageParam values
+ * @param MessageParam|MessageValue|string|int|float ...$values
* @return MessageValue
*/
public function params( ...$values ) {
if ( $value instanceof MessageParam ) {
$this->params[] = $value;
} else {
- $this->params[] = new TextParam( ParamType::TEXT, $value );
+ $this->params[] = new ScalarParam( ParamType::TEXT, $value );
}
}
return $this;
* Chainable mutator which adds text parameters with a common type
*
* @param string $type One of the ParamType constants
- * @param mixed ...$values Scalar values
+ * @param MessageValue|string|int|float ...$values Scalar values
* @return MessageValue
*/
public function textParamsOfType( $type, ...$values ) {
foreach ( $values as $value ) {
- $this->params[] = new TextParam( $type, $value );
+ $this->params[] = new ScalarParam( $type, $value );
}
return $this;
}
* Chainable mutator which adds list parameters with a common type
*
* @param string $listType One of the ListType constants
- * @param array ...$values Each value should be an array of list items.
+ * @param (MessageParam|MessageValue|string|int|float)[] ...$values Each value
+ * is an array of items suitable to pass as $params to ListParam::__construct()
* @return MessageValue
*/
public function listParamsOfType( $listType, ...$values ) {
}
/**
- * Chainable mutator which adds parameters of type text.
+ * Chainable mutator which adds parameters of type text (ParamType::TEXT).
*
- * @param string ...$values
+ * @param MessageValue|string|int|float ...$values
* @return MessageValue
*/
public function textParams( ...$values ) {
}
/**
- * Chainable mutator which adds numeric parameters
+ * Chainable mutator which adds numeric parameters (ParamType::NUM).
*
- * @param mixed ...$values
+ * @param int|float ...$values
* @return MessageValue
*/
public function numParams( ...$values ) {
/**
* Chainable mutator which adds parameters which are a duration specified
- * in seconds. This is similar to timePeriodParams() except that the result
- * will be more verbose.
+ * in seconds (ParamType::DURATION_LONG).
+ *
+ * This is similar to shorDurationParams() except that the result will be
+ * more verbose.
*
* @param int|float ...$values
* @return MessageValue
}
/**
- * Chainable mutator which adds parameters which are a time period in seconds.
- * This is similar to durationParams() except that the result will be more
+ * Chainable mutator which adds parameters which are a duration specified
+ * in seconds (ParamType::DURATION_SHORT).
+ *
+ * This is similar to longDurationParams() except that the result will be more
* compact.
*
* @param int|float ...$values
}
/**
- * Chainable mutator which adds parameters which are an expiry timestamp
- * as used in the MediaWiki database schema.
+ * Chainable mutator which adds parameters which are an expiry timestamp (ParamType::EXPIRY).
*
- * @param string ...$values
+ * @param string ...$values Timestamp as accepted by the Wikimedia\Timestamp library,
+ * or "infinity"
* @return MessageValue
*/
public function expiryParams( ...$values ) {
}
/**
- * Chainable mutator which adds parameters which are a number of bytes.
+ * Chainable mutator which adds parameters which are a number of bytes (ParamType::SIZE).
*
* @param int ...$values
* @return MessageValue
/**
* Chainable mutator which adds parameters which are a number of bits per
- * second.
+ * second (ParamType::BITRATE).
*
* @param int|float ...$values
* @return MessageValue
}
/**
- * Chainable mutator which adds parameters of type "raw".
+ * Chainable mutator which adds "raw" parameters (ParamType::RAW).
*
- * @param mixed ...$values
+ * Raw parameters are substituted after formatter processing. The caller is responsible
+ * for ensuring that the value will be safe for the intended output format, and
+ * documenting what that intended output format is.
+ *
+ * @param string ...$values
* @return MessageValue
*/
public function rawParams( ...$values ) {
}
/**
- * Chainable mutator which adds parameters of type "plaintext".
+ * Chainable mutator which adds plaintext parameters (ParamType::PLAINTEXT).
+ *
+ * Plaintext parameters are substituted after formatter processing. The value
+ * will be escaped by the formatter as appropriate for the target output format
+ * so as to be represented as plain text rather than as any sort of markup.
+ *
+ * @param string ...$values
+ * @return MessageValue
*/
public function plaintextParams( ...$values ) {
return $this->textParamsOfType( ParamType::PLAINTEXT, ...$values );
}
/**
- * Chainable mutator which adds comma lists. Each comma list is an array of
- * list elements, and each list element is either a MessageParam or a
- * string. String parameters are converted to parameters of type "text".
+ * Chainable mutator which adds comma lists (ListType::COMMA).
*
* The list parameters thus created are formatted as a comma-separated list,
* or some local equivalent.
*
- * @param (MessageParam|string)[] ...$values
+ * @param (MessageParam|MessageValue|string|int|float)[] ...$values Each value
+ * is an array of items suitable to pass as $params to ListParam::__construct()
* @return MessageValue
*/
public function commaListParams( ...$values ) {
}
/**
- * Chainable mutator which adds semicolon lists. Each semicolon list is an
- * array of list elements, and each list element is either a MessageParam
- * or a string. String parameters are converted to parameters of type
- * "text".
+ * Chainable mutator which adds semicolon lists (ListType::SEMICOLON).
*
* The list parameters thus created are formatted as a semicolon-separated
* list, or some local equivalent.
*
- * @param (MessageParam|string)[] ...$values
+ * @param (MessageParam|MessageValue|string|int|float)[] ...$values Each value
+ * is an array of items suitable to pass as $params to ListParam::__construct()
* @return MessageValue
*/
public function semicolonListParams( ...$values ) {
}
/**
- * Chainable mutator which adds pipe lists. Each pipe list is an array of
- * list elements, and each list element is either a MessageParam or a
- * string. String parameters are converted to parameters of type "text".
+ * Chainable mutator which adds pipe lists (ListType::PIPE).
*
* The list parameters thus created are formatted as a pipe ("|") -separated
* list, or some local equivalent.
*
- * @param (MessageParam|string)[] ...$values
+ * @param (MessageParam|MessageValue|string|int|float)[] ...$values Each value
+ * is an array of items suitable to pass as $params to ListParam::__construct()
* @return MessageValue
*/
public function pipeListParams( ...$values ) {
}
/**
- * Chainable mutator which adds text lists. Each text list is an array of
- * list elements, and each list element is either a MessageParam or a
- * string. String parameters are converted to parameters of type "text".
+ * Chainable mutator which adds natural-language lists (ListType::AND).
*
* The list parameters thus created, when formatted, are joined as in natural
* language. In English, this means a comma-separated list, with the last
dépôts / lhc / web / wiklou.git / blobdiff