vendor/zendframework/zend-i18n/doc/book/view-helpers.md

   1 # View Helpers
   2
   3 zend-i18n ships with a set of zend-view helper classes related to
   4 internationalization: e.g., formatting a date, formatting currency, or
   5 displaying translated content.
   6
   7 See the [zend-view helpers documentation](http://framework.zend.com/manual/current/en/modules/zend.view.helpers.html#zend-view-helpers)
   8 for more information.
   9
  10 ## CurrencyFormat Helper
  11
  12 The `CurrencyFormat` view helper can be used to simplify rendering of localized
  13 currency values. It acts as a wrapper for the `NumberFormatter` class within the
  14 internationalization extension (ext/intl).
  15
  16 ### Basic Usage
  17
  18 ```php
  19 // Within your view:
  20
  21 echo $this->currencyFormat(1234.56, 'USD', null, 'en_US');
  22 // Returns: "$1,234.56"
  23
  24 echo $this->currencyFormat(1234.56, 'EUR', null, 'de_DE');
  25 // Returns: "1.234,56 €"
  26
  27 echo $this->currencyFormat(1234.56, 'USD', true, 'en_US');
  28 // Returns: "$1,234.56"
  29
  30 echo $this->currencyFormat(1234.56, 'USD', false, 'en_US');
  31 // Returns: "$1,235"
  32
  33 echo $this->currencyFormat(12345678.90, 'EUR', true, 'de_DE', '#0.# kg');
  34 // Returns: "12345678,90 kg"
  35
  36 echo $this->currencyFormat(12345678.90, 'EUR', false, 'de_DE', '#0.# kg');
  37 // Returns: "12345679 kg"
  38 ```
  39
  40 ### Method description
  41
  42 ```php
  43 currencyFormat(
  44     float $number [,
  45     string $currencyCode = null [,
  46     bool $showDecimals = null [,
  47     string $locale = null [,
  48     string $pattern = null
  49 ] ] ] ]) : string
  50 ```
  51
  52 where:
  53
  54 - `$number`: the numeric currency value.
  55 - `$currencyCode`: the 3-letter ISO 4217 currency code indicating the currency
  56   to use. If unset, it will use the default value current in the helper
  57   instance (`null` by default).
  58 - `$showDecimals`: Boolean `false` indicates that no decimals should be
  59   represented. If unset, it will use the value current in the helper instance
  60   (`true` by default).
  61 - `$locale`: Locale in which the currency would be formatted (locale name, e.g.
  62   `en_US`). If unset, it will use the default locale (default is the value of
  63   `Locale::getDefault()`).
  64 - `$pattern`: Pattern string the formatter should use. If unset, it will use the
  65   value current in the helper instance (`null` by default).
  66
  67
  68 ### Available Functionality
  69
  70 #### Set the currency code and the locale
  71
  72 The `$currencyCode` and `$locale` options can be set prior to formatting and
  73 will be applied each time the helper is used:
  74
  75 ```php
  76 // Within your view
  77
  78 $this->plugin('currencyformat')->setCurrencyCode('USD')->setLocale('en_US');
  79
  80 echo $this->currencyFormat(1234.56);
  81 // This returns: "$1,234.56"
  82
  83 echo $this->currencyFormat(5678.90);
  84 // This returns: "$5,678.90"
  85 ```
  86
  87 The method signatures are:
  88
  89 ```php
  90 setCurrencyCode(string $currencyCode) : CurrencyFormat
  91 ```
  92
  93 where `$currencyCode` is the 3-letter ISO 4217 currency code, and
  94
  95 ```php
  96 setLocale(string $locale) : CurrencyFormat
  97 ```
  98
  99 where `$locale` is the locale with which to format the number.
 100
 101 #### Show decimals
 102
 103 ```php
 104 // Within your view
 105
 106 $this->plugin('currencyformat')->setShouldShowDecimals(false);
 107
 108 echo $this->currencyFormat(1234.56, 'USD', null, 'en_US');
 109 // This returns: "$1,235"
 110 ```
 111
 112 with the following method signature:
 113
 114 ```php
 115 setShouldShowDecimals(bool $showDecimals) : CurrencyFormat
 116 ```
 117
 118 where `$showDecimals` indicates whether or not decimal values will be displayed.
 119
 120 #### Set the currency pattern
 121
 122 ```php
 123 // Within your view
 124
 125 $this->plugin('currencyformat')->setCurrencyPattern('#0.# kg');
 126
 127 echo $this->currencyFormat(12345678.90, 'EUR', null, 'de_DE');
 128 // This returns: "12345678,90 kg"
 129 ```
 130
 131 with the following method signature:
 132
 133 ```php
 134 setCurrencyPattern(string $currencyPattern) : CurrencyFormat
 135 ```
 136
 137 where `$currencyPattern` is a valid [ICU DecimalFormat pattern](http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html#details);
 138 see the [NumberFormatter::setPattern() documentation](http://php.net/manual/numberformatter.setpattern.php)
 139 for more information.
 140
 141 ## DateFormat Helper
 142
 143 The `DateFormat` view helper can be used to simplify rendering of localized
 144 date/time values. It acts as a wrapper for the `IntlDateFormatter` class within
 145 ext/intl.
 146
 147 ### Basic Usage
 148
 149 ```php
 150 // Within your view
 151
 152 // Date and Time
 153 echo $this->dateFormat(
 154     new DateTime(),
 155     IntlDateFormatter::MEDIUM, // date
 156     IntlDateFormatter::MEDIUM, // time
 157     "en_US"
 158 );
 159 // This returns: "Jul 2, 2012 6:44:03 PM"
 160
 161 // Date Only
 162 echo $this->dateFormat(
 163     new DateTime(),
 164     IntlDateFormatter::LONG, // date
 165     IntlDateFormatter::NONE, // time
 166     "en_US"
 167 );
 168 // This returns: "July 2, 2012"
 169
 170 // Time Only
 171 echo $this->dateFormat(
 172     new DateTime(),
 173     IntlDateFormatter::NONE,  // date
 174     IntlDateFormatter::SHORT, // time
 175     "en_US"
 176 );
 177 // This returns: "6:44 PM"
 178 ```
 179
 180 ### Method description
 181
 182 ```php
 183 dateFormat(
 184     mixed $date [,
 185     int $dateType = null [,
 186     int $timeType = null [,
 187     string $locale = null
 188 ] ] ]) : string
 189 ```
 190
 191 where:
 192
 193 - `$date`: The value to format. This may be a `DateTime` instance, an integer
 194   representing a Unix timestamp value, or an array in the format returned by
 195   `localtime()`.
 196 - `$dateType`: Date type to use (none, short, medium, long, full). This is one
 197   of the [IntlDateFormatter constants](http://www.php.net/manual/class.intldateformatter.php#intl.intldateformatter-constants).
 198   Defaults to `IntlDateFormatter::NONE`.
 199 - `$timeType`: Time type to use (none, short, medium, long, full). This is one
 200   of the [IntlDateFormatter constants](http://www.php.net/manual/class.intldateformatter.php#intl.intldateformatter-constants).
 201   Defaults to `IntlDateFormatter::NONE`.
 202 - `$locale`: Locale in which the date would be formatted (locale name, e.g.
 203   `en_US`). If unset, it will use the default locale (return value of
 204   `Locale::getDefault()`).
 205
 206 ### Public Methods
 207
 208 The `$locale` option can be set prior to formatting with the `setLocale()`
 209 method and will be applied each time the helper is used.
 210
 211 By default, the system's default timezone will be used when formatting. This
 212 overrides any timezone that may be set inside a `DateTime` object. To change the
 213 timezone when formatting, use the `setTimezone()` method.
 214
 215 ```php
 216 // Within your view
 217 $this->plugin('dateFormat')
 218     ->setTimezone('America/New_York')
 219     ->setLocale('en_US');
 220
 221 echo $this->dateFormat(new DateTime(), IntlDateFormatter::MEDIUM);  // "Jul 2, 2012"
 222 echo $this->dateFormat(new DateTime(), IntlDateFormatter::SHORT);   // "7/2/12"
 223 ```
 224
 225 ## NumberFormat Helper
 226
 227 The `NumberFormat` view helper can be used to simplify rendering of
 228 locale-specific number and/or percentage strings. It acts as a wrapper for the
 229 `NumberFormatter` class within ext/intl.
 230
 231 ### Basic Usage
 232
 233 ```php
 234 // Within your view
 235
 236 // Example of Decimal formatting:
 237 echo $this->numberFormat(
 238     1234567.891234567890000,
 239     NumberFormatter::DECIMAL,
 240     NumberFormatter::TYPE_DEFAULT,
 241     'de_DE'
 242 );
 243 // This returns: "1.234.567,891"
 244
 245 // Example of Percent formatting:
 246 echo $this->numberFormat(
 247     0.80,
 248     NumberFormatter::PERCENT,
 249     NumberFormatter::TYPE_DEFAULT,
 250     'en_US'
 251 );
 252 // This returns: "80%"
 253
 254 // Example of Scientific notation formatting:
 255 echo $this->numberFormat(
 256     0.00123456789,
 257     NumberFormatter::SCIENTIFIC,
 258     NumberFormatter::TYPE_DEFAULT,
 259     'fr_FR'
 260 );
 261 // This returns: "1,23456789E-3"
 262 ```
 263
 264 ### Method description
 265
 266 ```php
 267 numberFormat(
 268     int|float $number [,
 269     int $formatStyle = null [,
 270     int $formatType = null [,
 271     string $locale = null [,
 272     int $decimals = null [,
 273     array $textAttributes = null
 274 ] ] ] ] ]) : string
 275 ```
 276
 277 where:
 278
 279 - `$number`: the number to format.
 280 - `$formatStyle`: one of the `NumberFormatter` styles:
 281   `NumberFormatter::DECIMAL`, `NumberFormatter::CURRENCY`, etc.
 282 - `$formatType`: one of the `NumberFormatter` types:
 283   `NumberFormatter::TYPE_DEFAULT` (basic numeric),
 284   `NumberFormatter::TYPE_CURRENCY`, etc.
 285 - `$locale`: a valid locale to use when formatting the number.
 286 - `$decimals`: the number of digits beyond the decimal point to display.
 287 - `$textAttributes`: text attributes to use with the number (e.g., prefix and/or
 288   suffix for positive/negative numbers, currency code):
 289   `NumberFormatter::POSITIVE_PREFIX`, `NumberFormatter::NEGATIVE_PREFIX`, etc.
 290
 291 ### Public Methods
 292
 293 Each of the `$formatStyle`, `$formatType`, `$locale`, and `$textAttributes`
 294 options can be set prior to formatting and will be applied each time the helper
 295 is used.
 296
 297 ```php
 298 // Within your view
 299 $this->plugin("numberformat")
 300             ->setFormatStyle(NumberFormatter::PERCENT)
 301             ->setFormatType(NumberFormatter::TYPE_DOUBLE)
 302             ->setLocale("en_US")
 303             ->setTextAttributes([
 304                 NumberFormatter::POSITIVE_PREFIX => '^ ',
 305                 NumberFormatter::NEGATIVE_PREFIX => 'v ',
 306             ]);
 307
 308 echo $this->numberFormat(0.56);   // "^ 56%"
 309 echo $this->numberFormat(-0.90);  // "v 90%"
 310 ```
 311
 312 ## Plural Helper
 313
 314 Most languages have specific rules for handling plurals. For instance, in
 315 English, we say "0 cars" and "2 cars" (plural) while we say "1 car" (singular).
 316 On the other hand, French uses the singular form for both 0 and 1 ("0 voiture"
 317 and "1 voiture") and the plural form otherwise ("3 voitures").
 318
 319 Therefore we often need to handle plural cases even without translation (mono-lingual
 320 application). The `Plural` helper was created for this.
 321
 322 > ### Plural helper does not translate
 323 >
 324 > If you need to handle both plural cases *and* translations, you must use the
 325 > `TranslatePlural` helper; `Plural` does not translate.
 326
 327 Internally, the `Plural` helper uses the `Zend\I18n\Translator\Plural\Rule` class to handle rules.
 328
 329 ### Setup
 330
 331 Defining plural rules is left to the developer. To help you with this process,
 332 here are some links with up-to-date plural rules for tons of languages:
 333
 334 - [http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html)
 335 - [https://developer.mozilla.org/en-US/docs/Localization_and_Plurals](https://developer.mozilla.org/en-US/docs/Localization_and_Plurals)
 336
 337 ### Basic Usage
 338
 339 First, define a rule. As an example, you could add the following code in your
 340 `Module` class:
 341
 342 ```php
 343 // Get the ViewHelperPlugin Manager from the ServiceManager, so we can fetch the
 344 // Plural helper and add the plural rule for the application's language:
 345 $viewHelperManager = $serviceManager->get('ViewHelperManager');
 346 $pluralHelper      = $viewHelperManager->get('Plural');
 347
 348 // Here is the rule for French
 349 $pluralHelper->setPluralRule('nplurals=2; plural=(n==0 || n==1 ? 0 : 1)');
 350 ```
 351
 352 The string reads as follows:
 353
 354 1. First, we specify how many plural forms we have. For French, only two (singular/plural).
 355 2. Next, we specify the rule. Here, if the count is 0 or 1, this is rule n°0
 356    (singular) while it's rule n°1 otherwise.
 357
 358 As noted earlier earlier, English considers "1" as singular and "0/other" as
 359 plural. Here is how that would be declared:
 360
 361 ```php
 362 // Here is the rule for English
 363 $pluralHelper->setPluralRule('nplurals=2; plural=(n==1 ? 0 : 1)');
 364 ```
 365
 366 Now that we have defined the rule, we can use it in our views:
 367
 368 ```php
 369 // Within a view script...
 370 // If the rule defined in Module.php is the English one:
 371
 372 echo $this->plural(array('car', 'cars'), 0); // prints "cars"
 373 echo $this->plural(array('car', 'cars'), 1); // prints "car"
 374
 375 // If the rule defined in Module.php is the French one:
 376 echo $this->plural(array('voiture', 'voitures'), 0); // prints "voiture"
 377 echo $this->plural(array('voiture', 'voitures'), 1); // prints "voiture"
 378 echo $this->plural(array('voiture', 'voitures'), 2); // prints "voitures"
 379 ```
 380
 381 ## Translate Helper
 382
 383 The `Translate` view helper can be used to translate content. It acts as a
 384 wrapper for the `Zend\I18n\Translator\Translator` class.
 385
 386 ### Setup
 387
 388 Before using the `Translate` view helper, you must have first created a
 389 `Translator` object and have attached it to the view helper. If you use the
 390 `Zend\View\HelperPluginManager` to invoke the view helper, this will be done
 391 automatically for you.
 392
 393 ### Basic Usage
 394
 395 ```php
 396 // Within your view...
 397
 398 echo $this->translate("Some translated text.");
 399 echo $this->translate("Translated text from a custom text domain.", "customDomain");
 400 echo sprintf($this->translate("The current time is %s."), $currentTime);
 401 echo $this->translate("Translate in a specific locale", "default", "de_DE");
 402 ```
 403
 404 ### Method description
 405
 406 ```php
 407 translate(
 408     string $message [,
 409     string $textDomain = null [,
 410     string $locale = null
 411 ] ]) : string
 412 ```
 413
 414 where:
 415
 416 - `$message`: The message to translate.
 417 - `$textDomain`: The text domain/context of the translation; defaults to
 418   "default".
 419 - `$locale`: Locale to which the message should be translated (locale name, e.g.
 420   `en_US`). If unset, it will use the default locale (return value of
 421   `Locale::getDefault()`).
 422
 423 ### Gettext
 424
 425 The `xgettext` utility can be used to compile `*.po` files from PHP source files containing the
 426 translate view helper.
 427
 428 ```bash
 429 $ xgettext --language=php --add-location --keyword=translate my-view-file.phtml
 430 ```
 431
 432 See the [Gettext Wikipedia page](http://en.wikipedia.org/wiki/Gettext) for more information.
 433
 434 ### Public Methods
 435
 436 Public methods for setting a `Zend\I18n\Translator\Translator` and a default
 437 text domain are inherited from the [AbstractTranslatorHelper](#abstract-translator-helper).
 438
 439 ## TranslatePlural Helper
 440
 441 The `TranslatePlural` view helper can be used to translate words which take into
 442 account numeric meanings. English, for example, has a singular definition of
 443 "car", for one car, and the plural definition, "cars", meaning zero "cars"
 444 or more than one car. Other languages like Russian or Polish have more plurals
 445 with different rules.
 446
 447 The helper acts as a wrapper for the `Zend\I18n\Translator\Translator` class.
 448
 449 ### Setup
 450
 451 Before using the `TranslatePlural` view helper, you must have first created a
 452 `Translator` object and have attached it to the view helper. If you use the
 453 `Zend\View\HelperPluginManager` to invoke the view helper, this will be done
 454 automatically for you.
 455
 456 ### Basic Usage
 457
 458 ```php
 459 // Within your view
 460 echo $this->translatePlural("car", "cars", $num);
 461
 462 // Use a custom domain
 463 echo $this->translatePlural("monitor", "monitors", $num, "customDomain");
 464
 465 // Change locale
 466 echo $this->translatePlural("locale", "locales", $num, "default", "de_DE");
 467 ```
 468
 469 ### Method description
 470
 471 ```php
 472 translatePlural(
 473     string $singular,
 474     string $plural,
 475     int $number [,
 476     string $textDomain = null [,
 477     string $locale = null
 478 ] ]) : string
 479 ```
 480
 481 where:
 482
 483 - `$singular`: The message to use for singular values.
 484 - `$plural`: The message to use for plural values.
 485 - `$number`: The number to evaluate in order to determine which number to use.
 486 - `$textDomain`: The text domain/context of the translation; defaults to
 487   "default".
 488 - `$locale`: Locale to which the message should be translated (locale name, e.g.
 489   `en_US`). If unset, it will use the default locale (return value of
 490   `Locale::getDefault()`).
 491
 492 ### Public Methods
 493
 494 Public methods for setting a `Zend\I18n\Translator\Translator` and a default
 495 text domain are inherited from the [AbstractTranslatorHelper](#abstract-translator-helper).
 496
 497 ## Abstract Translator Helper
 498
 499 The `AbstractTranslatorHelper` view helper is used as a base abstract class for
 500 any helpers that need to translate content. It provides an implementation for
 501 the `Zend\I18n\Translator\TranslatorAwareInterface`, allowing translator
 502 injection as well as text domain injection.
 503
 504 ### Public Methods
 505
 506 #### setTranslator()
 507
 508 ```php
 509 setTranslator(
 510     Translator $translator [ ,
 511     string $textDomain = null
 512 ] ) : void
 513 ```
 514
 515 Sets the `Zend\I18n\Translator\Translator` instance to use in the helper. The
 516 `$textDomain` argument is optional, and provided as a convenienct to allow
 517 setting both the translator and text domain simultaneously.
 518
 519 #### getTranslator()
 520
 521 ```php
 522 getTranslator() : Translator
 523 ```
 524
 525 Returns the `Zend\I18n\Translator\Translator` instance used by the helper.
 526
 527 #### hasTranslator()
 528
 529 ```php
 530 hasTranslator() : bool
 531 ```
 532
 533 Returns true if the helper composes a `Zend\I18n\Translator\Translator` instance.
 534
 535 #### setTranslatorEnabled()
 536
 537 ```php
 538 setTranslatorEnabled(bool $enabled) : void
 539 ```
 540
 541 Sets whether or not translations are enabled.
 542
 543 #### isTranslatorEnabled()
 544
 545 ```php
 546 isTranslatorEnabled() : bool
 547 ```
 548
 549 Returns true if translations are enabled.
 550
 551 #### setTranslatorTextDomain()
 552
 553 ```php
 554 setTranslatorTextDomain(string $textDomain) : void
 555 ```
 556
 557 Sets the default translation text domain to use with the helper.
 558
 559 #### getTranslatorTextDomain()
 560
 561 ```php
 562 getTranslatorTextDomain() : string
 563 ```
 564
 565 Returns the current text domain used by the helper.