includes/libs/Message/MessageValue.php

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