Merge branch 'docs/28'

Close #28

docs/book/view-helpers/currency-format.md

@@ -0,0 +1,145 @@
+# CurrencyFormat
+
+The `CurrencyFormat` view helper can be used to simplify **rendering of
+localized currency values**. It acts as a wrapper for the
+[`NumberFormatter` class](https://www.php.net/NumberFormatter) within the PHP's
+internationalization extension (`ext/intl`).
+
+## Basic Usage
+
+```php
+echo $this->currencyFormat(1234.56, 'USD'); // '$1,234.56'
+```
+
+By default, if no locale is provided, `CurrencyFormat` will use the system
+locale provided by PHP's `Locale` class and the `getDefault()` method.
+
+(The above example assumes that the environment locale is set to `en_US`.)
+
+## Using Currency Code
+
+```php fct_label="Invoke Usage"
+echo $this->currencyFormat(1234.56, 'EUR'); // '1.234,56 €'
+```
+
+```php fct_label="Setter Usage"
+$this->plugin('currencyFormat')->setCurrencyCode('EUR');
+
+echo $this->currencyFormat(1234.56); // '1.234,56 €'
+```
+
+(The above example assumes that the environment locale is set to `de`.)
+
+### Get current Value
+
+To get the current value of this option, use the `getCurrencyCode()` method.
+
+```php
+$this->plugin('currencyFormat')->setCurrencyCode('USD');
+
+echo $this->plugin('currencyFormat')->getCurrencyCode(); // 'USD'
+```
+
+### Default Value
+
+The default value of this option is `null`.
+
+## Show or hide Decimals
+
+```php fct_label="Invoke Usage"
+echo $this->currencyFormat(1234.56, 'EUR', false); // '1.234 €'
+```
+
+```php fct_label="Setter Usage"
+$this->plugin('currencyFormat')->setShouldShowDecimals(false);
+
+echo $this->currencyFormat(1234.56); // '1.234 €'
+```
+
+(The above example assumes that the environment locale is set to `de`.)
+
+### Get current Value
+
+To get the current value of this option, use the `shouldShowDecimals()` method.
+
+```php
+$this->plugin('currencyFormat')->setShouldShowDecimals(true);
+
+echo $this->plugin('currencyFormat')->shouldShowDecimals(); // true
+```
+
+### Default Value
+
+The default value of this option is `null` that means the decimals are showing.
+
+## Using Locale
+
+```php fct_label="Invoke Usage"
+echo $this->currencyFormat(1234.56, 'EUR', null, 'de'); // '1.234,56 €'
+```
+
+```php fct_label="Setter Usage"
+$this->plugin('currencyFormat')->setLocale('de');
+
+echo $this->currencyFormat(1234.56, 'EUR'); // '1.234,56 €'
+```
+
+### Get current Value
+
+To get the current value of this option, use the `getLocale()` method.
+
+```php
+$this->plugin('currencyFormat')->setLocale('de');
+
+echo $this->plugin('currencyFormat')->getLocale(); // 'de'
+```
+
+### Default Value
+
+By default, if no locale is provided, `CurrencyFormat` will use the system
+locale provided by PHP's `Locale::getDefault()`.
+
+## Define custom Pattern
+
+```php fct_label="Invoke Usage"
+echo $this->currencyFormat(1234.56, 'EUR', null, 'de', '#0.# kg'); // '12345678,90 kg'
+```
+
+```php fct_label="Setter Usage"
+$this->plugin('currencyformat')->setCurrencyPattern('#0.# kg');
+
+echo $this->currencyFormat(1234.56, 'EUR'); // '12345678,90 kg'
+```
+
+(The above example assumes that the environment locale is set to `de`.)
+
+Valid patterns are documented at
+[ICU DecimalFormat](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classDecimalFormat.html#details);
+see the [NumberFormatter::setPattern documentation](https://www.php.net/manual/numberformatter.setpattern.php)
+for more information.
+
+### Get current Value
+
+To get the current value of this option, use the `getCurrencyPattern()` method.
+
+```php
+$this->plugin('currencyFormat')->setCurrencyPattern('#0.# kg');
+
+echo $this->plugin('currencyFormat')->getCurrencyPattern(); // '#0.# kg'
+```
+
+### Default Value
+
+The default value of this option is `null`.
+
+## Multiple Executions
+
+If the different options are set prior to formatting then it will be applied
+each time the helper is used.
+
+```php
+$this->plugin('currencyformat')->setCurrencyCode('USD')->setLocale('en_US');
+
+echo $this->currencyFormat(1234.56); // '$1,234.56'
+echo $this->currencyFormat(5678.90); // '$5,678.90'
+```

docs/book/view-helpers/date-format.md

@@ -0,0 +1,186 @@
+# DateFormat
+
+The `DateFormat` view helper can be used to simplify **rendering of localized
+date/time values**. It acts as a wrapper for the
+[`IntlDateFormatter` class](https://www.php.net/IntlDateFormatter) within PHP's
+internationalization extension (`ext/intl`).
+
+## Basic Usage
+
+The value for the date must be a
+[`DateTimeInterface`](https://www.php.net/DateTimeInterface) object, an integer
+representing a Unix timestamp value, or an array in the format returned by
+[`localtime()` function](https://www.php.net/localtime).
+
+Example with a `DateTime` instance:
+
+```php
+echo $this->dateFormat(new DateTime()); // '20190222 09:07 PM'
+```
+
+Example with an Unix timestamp:
+
+```php
+echo $this->dateFormat(1550870660); // '20190222 04:24 PM'
+```
+
+Example with the format of `localtime()`:
+
+```php
+echo $this->dateFormat([
+    'tm_sec'  => 0,   // seconds, 0 to 59
+    'tm_min'  => 30,  // minutes, 0 to 59
+    'tm_hour' => 12,  // hours, 0 to 23
+    'tm_mday' => 5,   // day of the month, 1 to 31
+    'tm_mon'  => 4,   // month of the year, 0 (Jan) to 11 (Dec)
+    'tm_year' => 119, // years since 1900
+]); // '20190505 12:30 PM'
+```
+
+By default, if no locale is provided, `DateFormat` will use the system
+locale provided by PHP's `Locale` class and the `getDefault()` method.
+
+(The above example assumes that the environment locale is set to `en_US`.)
+
+### More Examples
+
+Format date and time:
+
+```php
+echo $this->dateFormat(
+    new DateTime(),
+    IntlDateFormatter::MEDIUM, // Date
+    IntlDateFormatter::MEDIUM  // Time
+); // 'Feb 22, 2019, 9:07:38 PM'
+```
+
+Format only a date:
+
+```php
+echo $this->dateFormat(
+    new DateTime(),
+    IntlDateFormatter::LONG, // Date
+    IntlDateFormatter::NONE  // Time
+); // 'Feb 22, 2019'
+```
+
+Format only a time:
+
+```php
+echo $this->dateFormat(
+    new DateTime(),
+    IntlDateFormatter::NONE, // Date
+    IntlDateFormatter::SHORT // Time
+); // '9:07 PM'
+```
+
+(The above examples assumes that the environment locale is set to `en_US`.)
+
+## Using Date Type
+
+Sets date type to use (none, short, medium, long, full).
+
+```php
+echo $this->dateFormat(new DateTime(), IntlDateFormatter::MEDIUM); // 'Feb 22, 2019'
+```
+
+(The above example assumes that the environment locale is set to `en_US`.)
+
+Possible values for the date type option are the following
+[constants of PHP's `IntlDateFormatter` class](https://www.php.net/manual/class.intldateformatter.php#intl.intldateformatter-constants):
+
+* `IntlDateFormatter::NONE` - Do not include this element
+* `IntlDateFormatter::FULL` - Fullstyle (Tuesday, April 12, 1952 AD)
+* `IntlDateFormatter::LONG` - Long style (January 12, 1952)
+* `IntlDateFormatter::MEDIUM` - Medium style (Jan 12, 1952)
+* `IntlDateFormatter::SHORT` - Short style (12/13/52)
+
+### Default Value
+
+The default value of this option is `IntlDateFormatter::NONE`.
+
+## Using Time Type
+
+Sets time type to use (none, short, medium, long, full).
+
+```php
+echo $this->dateFormat(new DateTime(), IntlDateFormatter::NONE, IntlDateFormatter::MEDIUM);
+// '9:41:58 PM'
+```
+
+(The above example assumes that the environment locale is set to `en_US`.)
+
+Possible values for the date type option are the following
+[constants of PHP's `IntlDateFormatter` class](https://www.php.net/manual/class.intldateformatter.php#intl.intldateformatter-constants):
+
+* `IntlDateFormatter::NONE` - Do not include this element
+* `IntlDateFormatter::FULL` - Fullstyle (3:30:42pm PST)
+* `IntlDateFormatter::LONG` - Long style (3:30:32pm)
+* `IntlDateFormatter::MEDIUM` - Medium style (3:30:32pm)
+* `IntlDateFormatter::SHORT` - Short style (3:30pm)
+
+### Default Value
+
+The default value of this option is `IntlDateFormatter::NONE`.
+
+## Using Locale
+
+```php fct_label="Invoke Usage"
+echo $this->dateFormat(new DateTime(), null, null, 'de_DE');
+// 'Freitag, 22. Februar 2019 um 21:16:37 GMT'
+```
+
+```php fct_label="Setter Usage"
+$this->plugin('dateFormat')->setLocale('de_DE');
+
+echo $this->dateFormat(new DateTime()); // 'Freitag, 22. Februar 2019 um 21:16:37 GMT'
+```
+
+```php fct_label="Locale Class Usage"
+Locale::setDefault('de_DE');
+
+echo $this->dateFormat(new DateTime()); // 'Freitag, 22. Februar 2019 um 21:16:37 GMT'
+```
+
+### Get current Value
+
+To get the current value of this option, use the `getLocale()` method.
+
+```php
+$this->plugin('dateFormat')->setLocale('en_US');
+
+echo $this->plugin('dateFormat')->getLocale(); // 'en_US'
+```
+
+### Default Value
+
+By default, if no locale is provided, `DateFormat` will use the system
+locale provided by PHP's `Locale::getDefault()`.
+
+## Using Timezone
+
+By default, the system's default timezone will be used when formatting. This
+overrides any timezone that may be set inside a `DateTime` object. To change the
+timezone when formatting, use the `setTimezone()` method.
+
+```php
+$this->plugin('dateFormat')->setTimezone('America/New_York');
+
+echo $this->dateFormat(new DateTime(), null, null, 'en_US');
+// 'Friday, February 22, 2019 at 4:20:21 PM Eastern Standard Time'
+```
+
+### Get current Value
+
+To get the current value of this option, use the `getTimezone()` method.
+
+```php
+$this->plugin('dateFormat')->setTimezone('America/New_York');
+
+echo $this->plugin('dateFormat')->getTimezone(); // 'America/New_York'
+```
+
+### Default Value
+
+By default, if no timezone is provided, `DateFormat` will use the system
+timezone provided by PHP's `date_default_timezone_get()`.