3 namespace Wikimedia\Message
;
6 * Value object representing a message for i18n.
8 * A MessageValue holds a key and an array of parameters. It can be converted
9 * to a string in a particular language using formatters obtained from an
10 * IMessageFormatterFactory.
12 * MessageValues are pure value objects and are safely newable.
18 /** @var MessageParam[] */
23 * @param (MessageParam|MessageValue|string|int|float)[] $params Values that are not instances
24 * of MessageParam are wrapped using ParamType::TEXT.
26 public function __construct( $key, $params = [] ) {
29 $this->params( ...$params );
37 public function getKey() {
42 * Get the parameter array
44 * @return MessageParam[]
46 public function getParams() {
51 * Chainable mutator which adds text parameters and MessageParam parameters
53 * @param MessageParam|MessageValue|string|int|float ...$values
54 * @return MessageValue
56 public function params( ...$values ) {
57 foreach ( $values as $value ) {
58 if ( $value instanceof MessageParam
) {
59 $this->params
[] = $value;
61 $this->params
[] = new ScalarParam( ParamType
::TEXT
, $value );
68 * Chainable mutator which adds text parameters with a common type
70 * @param string $type One of the ParamType constants
71 * @param MessageValue|string|int|float ...$values Scalar values
72 * @return MessageValue
74 public function textParamsOfType( $type, ...$values ) {
75 foreach ( $values as $value ) {
76 $this->params
[] = new ScalarParam( $type, $value );
82 * Chainable mutator which adds list parameters with a common type
84 * @param string $listType One of the ListType constants
85 * @param (MessageParam|MessageValue|string|int|float)[] ...$values Each value
86 * is an array of items suitable to pass as $params to ListParam::__construct()
87 * @return MessageValue
89 public function listParamsOfType( $listType, ...$values ) {
90 foreach ( $values as $value ) {
91 $this->params
[] = new ListParam( $listType, $value );
97 * Chainable mutator which adds parameters of type text (ParamType::TEXT).
99 * @param MessageValue|string|int|float ...$values
100 * @return MessageValue
102 public function textParams( ...$values ) {
103 return $this->textParamsOfType( ParamType
::TEXT
, ...$values );
107 * Chainable mutator which adds numeric parameters (ParamType::NUM).
109 * @param int|float ...$values
110 * @return MessageValue
112 public function numParams( ...$values ) {
113 return $this->textParamsOfType( ParamType
::NUM
, ...$values );
117 * Chainable mutator which adds parameters which are a duration specified
118 * in seconds (ParamType::DURATION_LONG).
120 * This is similar to shorDurationParams() except that the result will be
123 * @param int|float ...$values
124 * @return MessageValue
126 public function longDurationParams( ...$values ) {
127 return $this->textParamsOfType( ParamType
::DURATION_LONG
, ...$values );
131 * Chainable mutator which adds parameters which are a duration specified
132 * in seconds (ParamType::DURATION_SHORT).
134 * This is similar to longDurationParams() except that the result will be more
137 * @param int|float ...$values
138 * @return MessageValue
140 public function shortDurationParams( ...$values ) {
141 return $this->textParamsOfType( ParamType
::DURATION_SHORT
, ...$values );
145 * Chainable mutator which adds parameters which are an expiry timestamp (ParamType::EXPIRY).
147 * @param string ...$values Timestamp as accepted by the Wikimedia\Timestamp library,
149 * @return MessageValue
151 public function expiryParams( ...$values ) {
152 return $this->textParamsOfType( ParamType
::EXPIRY
, ...$values );
156 * Chainable mutator which adds parameters which are a number of bytes (ParamType::SIZE).
158 * @param int ...$values
159 * @return MessageValue
161 public function sizeParams( ...$values ) {
162 return $this->textParamsOfType( ParamType
::SIZE
, ...$values );
166 * Chainable mutator which adds parameters which are a number of bits per
167 * second (ParamType::BITRATE).
169 * @param int|float ...$values
170 * @return MessageValue
172 public function bitrateParams( ...$values ) {
173 return $this->textParamsOfType( ParamType
::BITRATE
, ...$values );
177 * Chainable mutator which adds "raw" parameters (ParamType::RAW).
179 * Raw parameters are substituted after formatter processing. The caller is responsible
180 * for ensuring that the value will be safe for the intended output format, and
181 * documenting what that intended output format is.
183 * @param string ...$values
184 * @return MessageValue
186 public function rawParams( ...$values ) {
187 return $this->textParamsOfType( ParamType
::RAW
, ...$values );
191 * Chainable mutator which adds plaintext parameters (ParamType::PLAINTEXT).
193 * Plaintext parameters are substituted after formatter processing. The value
194 * will be escaped by the formatter as appropriate for the target output format
195 * so as to be represented as plain text rather than as any sort of markup.
197 * @param string ...$values
198 * @return MessageValue
200 public function plaintextParams( ...$values ) {
201 return $this->textParamsOfType( ParamType
::PLAINTEXT
, ...$values );
205 * Chainable mutator which adds comma lists (ListType::COMMA).
207 * The list parameters thus created are formatted as a comma-separated list,
208 * or some local equivalent.
210 * @param (MessageParam|MessageValue|string|int|float)[] ...$values Each value
211 * is an array of items suitable to pass as $params to ListParam::__construct()
212 * @return MessageValue
214 public function commaListParams( ...$values ) {
215 return $this->listParamsOfType( ListType
::COMMA
, ...$values );
219 * Chainable mutator which adds semicolon lists (ListType::SEMICOLON).
221 * The list parameters thus created are formatted as a semicolon-separated
222 * list, or some local equivalent.
224 * @param (MessageParam|MessageValue|string|int|float)[] ...$values Each value
225 * is an array of items suitable to pass as $params to ListParam::__construct()
226 * @return MessageValue
228 public function semicolonListParams( ...$values ) {
229 return $this->listParamsOfType( ListType
::SEMICOLON
, ...$values );
233 * Chainable mutator which adds pipe lists (ListType::PIPE).
235 * The list parameters thus created are formatted as a pipe ("|") -separated
236 * list, or some local equivalent.
238 * @param (MessageParam|MessageValue|string|int|float)[] ...$values Each value
239 * is an array of items suitable to pass as $params to ListParam::__construct()
240 * @return MessageValue
242 public function pipeListParams( ...$values ) {
243 return $this->listParamsOfType( ListType
::PIPE
, ...$values );
247 * Chainable mutator which adds natural-language lists (ListType::AND).
249 * The list parameters thus created, when formatted, are joined as in natural
250 * language. In English, this means a comma-separated list, with the last
251 * two elements joined with "and".
253 * @param (MessageParam|string)[] ...$values
254 * @return MessageValue
256 public function textListParams( ...$values ) {
257 return $this->listParamsOfType( ListType
::AND, ...$values );
261 * Dump the object for testing/debugging
265 public function dump() {
267 foreach ( $this->params
as $param ) {
268 $contents .= $param->dump();
270 return '<message key="' . htmlspecialchars( $this->key
) . '">' .
271 $contents . '</message>';