includes/libs/Message/MessageValue.php

   1 <?php
   2
   3 namespace Wikimedia\Message;
   4
   5 /**
   6  * Value object representing a message for i18n.
   7  *
   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.
  11  *
  12  * MessageValues are pure value objects and are safely newable.
  13  */
  14 class MessageValue {
  15         /** @var string */
  16         private $key;
  17
  18         /** @var MessageParam[] */
  19         private $params;
  20
  21         /**
  22          * @param string $key
  23          * @param (MessageParam|MessageValue|string|int|float)[] $params Values that are not instances
  24          *  of MessageParam are wrapped using ParamType::TEXT.
  25          */
  26         public function __construct( $key, $params = [] ) {
  27                 $this->key = $key;
  28                 $this->params = [];
  29                 $this->params( ...$params );
  30         }
  31
  32         /**
  33          * Get the message key
  34          *
  35          * @return string
  36          */
  37         public function getKey() {
  38                 return $this->key;
  39         }
  40
  41         /**
  42          * Get the parameter array
  43          *
  44          * @return MessageParam[]
  45          */
  46         public function getParams() {
  47                 return $this->params;
  48         }
  49
  50         /**
  51          * Chainable mutator which adds text parameters and MessageParam parameters
  52          *
  53          * @param MessageParam|MessageValue|string|int|float ...$values
  54          * @return MessageValue
  55          */
  56         public function params( ...$values ) {
  57                 foreach ( $values as $value ) {
  58                         if ( $value instanceof MessageParam ) {
  59                                 $this->params[] = $value;
  60                         } else {
  61                                 $this->params[] = new ScalarParam( ParamType::TEXT, $value );
  62                         }
  63                 }
  64                 return $this;
  65         }
  66
  67         /**
  68          * Chainable mutator which adds text parameters with a common type
  69          *
  70          * @param string $type One of the ParamType constants
  71          * @param MessageValue|string|int|float ...$values Scalar values
  72          * @return MessageValue
  73          */
  74         public function textParamsOfType( $type, ...$values ) {
  75                 foreach ( $values as $value ) {
  76                         $this->params[] = new ScalarParam( $type, $value );
  77                 }
  78                 return $this;
  79         }
  80
  81         /**
  82          * Chainable mutator which adds list parameters with a common type
  83          *
  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
  88          */
  89         public function listParamsOfType( $listType, ...$values ) {
  90                 foreach ( $values as $value ) {
  91                         $this->params[] = new ListParam( $listType, $value );
  92                 }
  93                 return $this;
  94         }
  95
  96         /**
  97          * Chainable mutator which adds parameters of type text (ParamType::TEXT).
  98          *
  99          * @param MessageValue|string|int|float ...$values
 100          * @return MessageValue
 101          */
 102         public function textParams( ...$values ) {
 103                 return $this->textParamsOfType( ParamType::TEXT, ...$values );
 104         }
 105
 106         /**
 107          * Chainable mutator which adds numeric parameters (ParamType::NUM).
 108          *
 109          * @param int|float ...$values
 110          * @return MessageValue
 111          */
 112         public function numParams( ...$values ) {
 113                 return $this->textParamsOfType( ParamType::NUM, ...$values );
 114         }
 115
 116         /**
 117          * Chainable mutator which adds parameters which are a duration specified
 118          * in seconds (ParamType::DURATION_LONG).
 119          *
 120          * This is similar to shorDurationParams() except that the result will be
 121          * more verbose.
 122          *
 123          * @param int|float ...$values
 124          * @return MessageValue
 125          */
 126         public function longDurationParams( ...$values ) {
 127                 return $this->textParamsOfType( ParamType::DURATION_LONG, ...$values );
 128         }
 129
 130         /**
 131          * Chainable mutator which adds parameters which are a duration specified
 132          * in seconds (ParamType::DURATION_SHORT).
 133          *
 134          * This is similar to longDurationParams() except that the result will be more
 135          * compact.
 136          *
 137          * @param int|float ...$values
 138          * @return MessageValue
 139          */
 140         public function shortDurationParams( ...$values ) {
 141                 return $this->textParamsOfType( ParamType::DURATION_SHORT, ...$values );
 142         }
 143
 144         /**
 145          * Chainable mutator which adds parameters which are an expiry timestamp (ParamType::EXPIRY).
 146          *
 147          * @param string ...$values Timestamp as accepted by the Wikimedia\Timestamp library,
 148          *  or "infinity"
 149          * @return MessageValue
 150          */
 151         public function expiryParams( ...$values ) {
 152                 return $this->textParamsOfType( ParamType::EXPIRY, ...$values );
 153         }
 154
 155         /**
 156          * Chainable mutator which adds parameters which are a number of bytes (ParamType::SIZE).
 157          *
 158          * @param int ...$values
 159          * @return MessageValue
 160          */
 161         public function sizeParams( ...$values ) {
 162                 return $this->textParamsOfType( ParamType::SIZE, ...$values );
 163         }
 164
 165         /**
 166          * Chainable mutator which adds parameters which are a number of bits per
 167          * second (ParamType::BITRATE).
 168          *
 169          * @param int|float ...$values
 170          * @return MessageValue
 171          */
 172         public function bitrateParams( ...$values ) {
 173                 return $this->textParamsOfType( ParamType::BITRATE, ...$values );
 174         }
 175
 176         /**
 177          * Chainable mutator which adds "raw" parameters (ParamType::RAW).
 178          *
 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.
 182          *
 183          * @param string ...$values
 184          * @return MessageValue
 185          */
 186         public function rawParams( ...$values ) {
 187                 return $this->textParamsOfType( ParamType::RAW, ...$values );
 188         }
 189
 190         /**
 191          * Chainable mutator which adds plaintext parameters (ParamType::PLAINTEXT).
 192          *
 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.
 196          *
 197          * @param string ...$values
 198          * @return MessageValue
 199          */
 200         public function plaintextParams( ...$values ) {
 201                 return $this->textParamsOfType( ParamType::PLAINTEXT, ...$values );
 202         }
 203
 204         /**
 205          * Chainable mutator which adds comma lists (ListType::COMMA).
 206          *
 207          * The list parameters thus created are formatted as a comma-separated list,
 208          * or some local equivalent.
 209          *
 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
 213          */
 214         public function commaListParams( ...$values ) {
 215                 return $this->listParamsOfType( ListType::COMMA, ...$values );
 216         }
 217
 218         /**
 219          * Chainable mutator which adds semicolon lists (ListType::SEMICOLON).
 220          *
 221          * The list parameters thus created are formatted as a semicolon-separated
 222          * list, or some local equivalent.
 223          *
 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
 227          */
 228         public function semicolonListParams( ...$values ) {
 229                 return $this->listParamsOfType( ListType::SEMICOLON, ...$values );
 230         }
 231
 232         /**
 233          * Chainable mutator which adds pipe lists (ListType::PIPE).
 234          *
 235          * The list parameters thus created are formatted as a pipe ("|") -separated
 236          * list, or some local equivalent.
 237          *
 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
 241          */
 242         public function pipeListParams( ...$values ) {
 243                 return $this->listParamsOfType( ListType::PIPE, ...$values );
 244         }
 245
 246         /**
 247          * Chainable mutator which adds natural-language lists (ListType::AND).
 248          *
 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".
 252          *
 253          * @param (MessageParam|string)[] ...$values
 254          * @return MessageValue
 255          */
 256         public function textListParams( ...$values ) {
 257                 return $this->listParamsOfType( ListType::AND, ...$values );
 258         }
 259
 260         /**
 261          * Dump the object for testing/debugging
 262          *
 263          * @return string
 264          */
 265         public function dump() {
 266                 $contents = '';
 267                 foreach ( $this->params as $param ) {
 268                         $contents .= $param->dump();
 269                 }
 270                 return '<message key="' . htmlspecialchars( $this->key ) . '">' .
 271                         $contents . '</message>';
 272         }
 273 }