You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
201 lines
12 KiB
201 lines
12 KiB
10 years ago
|
Data Formatter
|
||
|
==============
|
||
|
|
||
10 years ago
|
For formatting of outputs Yii provides a formatter class to make data more readable for users.
|
||
10 years ago
|
[[yii\i18n\Formatter]] is a helper class that is registered as an [application component](structure-application-components.md) named `formatter` by default.
|
||
10 years ago
|
|
||
10 years ago
|
It provides a set of methods for data formatting purpose such as date/time values, numbers and other commonly used formats in a localized way.
|
||
|
The formatter can be used in two different ways.
|
||
10 years ago
|
|
||
10 years ago
|
1. Using the formatting methods (all formatter methods prefixed with `as`) directly:
|
||
10 years ago
|
|
||
|
```php
|
||
|
echo Yii::$app->formatter->asDate('2014-01-01', 'long'); // output: January 1, 2014
|
||
|
echo Yii::$app->formatter->asPercent(0.125, 2); // output: 12.50%
|
||
|
echo Yii::$app->formatter->asEmail('cebe@example.com'); // output: <a href="mailto:cebe@example.com">cebe@example.com</a>
|
||
|
echo Yii::$app->formatter->asBoolean(true); // output: Yes
|
||
10 years ago
|
// it also handles display of null values:
|
||
|
echo Yii::$app->formatter->asDate(null); // output: (Not set)
|
||
10 years ago
|
```
|
||
|
|
||
10 years ago
|
2. Using the [[yii\i18n\Formatter::format()|format()]] method and the format name.
|
||
|
This method is also used by widgets like [[yii\grid\GridView]] and [[yii\widgets\DetailView]] where you can specify
|
||
|
the data format of a column in the widget configuration.
|
||
10 years ago
|
|
||
|
```php
|
||
|
echo Yii::$app->formatter->format('2014-01-01', 'date'); // output: January 1, 2014
|
||
|
// you can also use an array to specify parameters for the format method:
|
||
|
// `2` is the value for the $decimals parameter of the asPercent()-method.
|
||
|
echo Yii::$app->formatter->format(0.125, ['percent', 2]); // output: 12.50%
|
||
|
```
|
||
|
|
||
|
All output of the formatter is localized when the [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed.
|
||
|
You can configure the [[yii\i18n\Formatter::locale|locale]] property of the formatter for this. If not configured, the
|
||
10 years ago
|
application [[yii\base\Application::language|language]] is used as the locale. See the [section on internationalization](tutorial-i18n.md) for more details.
|
||
10 years ago
|
The Formatter will then choose the correct format for dates and numbers according to the locale including names of month and
|
||
10 years ago
|
weekdays translated to the current language. Date formats are also affected by the [[yii\i18n\Formatter::timeZone|timeZone]]
|
||
|
which will also be taken from the application [[yii\base\Application::timeZone|timeZone]] if not configured explicitly.
|
||
10 years ago
|
|
||
10 years ago
|
For example the date format call will output different results for different locales:
|
||
10 years ago
|
|
||
|
```php
|
||
10 years ago
|
Yii::$app->formatter->locale = 'en-US';
|
||
|
echo Yii::$app->formatter->asDate('2014-01-01'); // output: January 1, 2014
|
||
|
Yii::$app->formatter->locale = 'de-DE';
|
||
|
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1. Januar 2014
|
||
|
Yii::$app->formatter->locale = 'ru-RU';
|
||
|
echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1 января 2014 г.
|
||
10 years ago
|
```
|
||
|
|
||
10 years ago
|
> Note that formatting may differ between different versions of the ICU library compiled with PHP and also based on the fact whether the
|
||
|
> [PHP intl extension](http://php.net/manual/en/book.intl.php) is installed or not. So to ensure your website works with the same output
|
||
|
> in all environments it is recommended to install the PHP intl extension in all environments and verify that the version of the ICU library
|
||
10 years ago
|
> is the same. See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
|
||
10 years ago
|
>
|
||
|
> Note also that even if the intl extension is installed, formatting date and time values for years >=2038 or <=1901
|
||
|
> on 32bit systems will fall back to the PHP implementation, which does not provide localized month and day names,
|
||
|
> because intl uses a 32bit UNIX timestamp internally. On a 64bit system the intl formatter is used in all cases if installed.
|
||
10 years ago
|
|
||
|
|
||
10 years ago
|
Configuring the formatter <span id="configuring-format"></span>
|
||
10 years ago
|
-------------------------
|
||
10 years ago
|
|
||
10 years ago
|
The default formats used by the formatter methods can be adjusted using the properties of the [[yii\i18n\Formatter|formatter class]].
|
||
10 years ago
|
You can adjust these values application wide by configuring the `formatter` component in your [application config](concept-configurations.md#application-configurations).
|
||
|
An example configuration is shown in the following.
|
||
10 years ago
|
For more details about the available properties check out the [[yii\i18n\Formatter|API documentation of the Formatter class]] and the following subsections.
|
||
10 years ago
|
|
||
10 years ago
|
```php
|
||
|
'components' => [
|
||
|
'formatter' => [
|
||
|
'dateFormat' => 'dd.MM.yyyy',
|
||
|
'decimalSeparator' => ',',
|
||
|
'thousandSeparator' => ' ',
|
||
|
'currencyCode' => 'EUR',
|
||
10 years ago
|
],
|
||
|
],
|
||
10 years ago
|
```
|
||
10 years ago
|
|
||
10 years ago
|
Formatting Date and Time values <span id="date-and-time"></span>
|
||
10 years ago
|
-------------------------------
|
||
10 years ago
|
|
||
10 years ago
|
The formatter class provides different methods for formatting date and time values. These are:
|
||
10 years ago
|
|
||
10 years ago
|
- [[yii\i18n\Formatter::asDate()|date]] - the value is formatted as a date e.g. `January 01, 2014`.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asTime()|time]] - the value is formatted as a time e.g. `14:23`.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asDatetime()|datetime]] - the value is formatted as date and time e.g. `January 01, 2014 14:23`.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asTimestamp()|timestamp]] - the value is formatted as a [unix timestamp](http://en.wikipedia.org/wiki/Unix_time) e.g. `1412609982`.
|
||
|
- [[yii\i18n\Formatter::asRelativeTime()|relativeTime]] - the value is formatted as the time interval between a date
|
||
|
and now in human readable form e.g. `1 hour ago`.
|
||
10 years ago
|
|
||
10 years ago
|
The date and time format for the [[yii\i18n\Formatter::asDate()|date]], [[yii\i18n\Formatter::asTime()|time]], and
|
||
10 years ago
|
[[yii\i18n\Formatter::asDatetime()|datetime]] methods can be specified globally by configuring the formatters
|
||
10 years ago
|
properties [[yii\i18n\Formatter::$dateFormat|$dateFormat]], [[yii\i18n\Formatter::$timeFormat|$timeFormat]], and
|
||
10 years ago
|
[[yii\i18n\Formatter::$datetimeFormat|$datetimeFormat]].
|
||
10 years ago
|
|
||
10 years ago
|
By default the formatter uses a shortcut format that is interpreted differently according to the currently active locale
|
||
10 years ago
|
so that dates and times are formatted in a way that is common for the users country and language.
|
||
10 years ago
|
There are four different shortcut formats available:
|
||
10 years ago
|
|
||
10 years ago
|
- `short` in `en_GB` locale will print for example `06/10/2014` for date and `15:58` for time, while
|
||
|
- `medium` will print `6 Oct 2014` and `15:58:42`,
|
||
|
- `long` will print `6 October 2014` and `15:58:42 GMT`,
|
||
|
- and `full` will print `Monday, 6 October 2014` and `15:58:42 GMT`.
|
||
10 years ago
|
|
||
10 years ago
|
Additionally you can specify custom formats using the syntax defined by the
|
||
|
[ICU Project](http://site.icu-project.org/) which is described in the ICU manual under the following URL:
|
||
|
<http://userguide.icu-project.org/formatparse/datetime>. Alternatively you can use the syntax that can be recognized by the
|
||
10 years ago
|
PHP [date()](http://php.net/manual/en/function.date.php) function using a string that is prefixed with `php:`.
|
||
10 years ago
|
|
||
10 years ago
|
```php
|
||
|
// ICU format
|
||
|
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06
|
||
|
// PHP date()-format
|
||
|
echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06
|
||
|
```
|
||
10 years ago
|
|
||
10 years ago
|
### Time zones <span id="time-zones"></span>
|
||
10 years ago
|
|
||
10 years ago
|
When formatting date and time values, Yii will convert them to the [[yii\i18n\Formatter::timeZone|configured time zone]].
|
||
10 years ago
|
Therefore the input value is assumed to be in UTC unless a time zone is explicitly given. For this reason
|
||
10 years ago
|
it is recommended to store all date and time values in UTC, preferably as a UNIX timestamp, which is always UTC by definition.
|
||
10 years ago
|
If the input value is in a time zone different from UTC, the time zone has to be stated explicitly like in the following example:
|
||
10 years ago
|
|
||
10 years ago
|
```php
|
||
|
// assuming Yii::$app->timeZone = 'Europe/Berlin';
|
||
|
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00
|
||
|
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00
|
||
|
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00
|
||
|
```
|
||
10 years ago
|
|
||
10 years ago
|
Since version 2.0.1 it is also possible to configure the time zone that is assumed for timestamps that do not include a time zone
|
||
|
identifier like the second example in the code above. You can set [[yii\i18n\Formatter::defaultTimeZone]] to the time zone you use for data storage.
|
||
|
|
||
10 years ago
|
> Note: As time zones are subject to rules made by the governments around the world and may change frequently, it is
|
||
|
> likely that you do not have the latest information in the time zone database installed on your system.
|
||
|
> You may refer to the [ICU manual](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data)
|
||
|
> for details on updating the time zone database.
|
||
|
> See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
|
||
|
|
||
|
|
||
10 years ago
|
Formatting Numbers <span id="numbers"></span>
|
||
10 years ago
|
------------------
|
||
10 years ago
|
|
||
10 years ago
|
For formatting numeric values the formatter class provides the following methods:
|
||
10 years ago
|
|
||
10 years ago
|
- [[yii\i18n\Formatter::asInteger()|integer]] - the value is formatted as an integer e.g. `42`.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asDecimal()|decimal]] - the value is formatted as a decimal number considering decimal and thousand
|
||
|
separators e.g. `2,542.123` or `2.542,123`.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asPercent()|percent]] - the value is formatted as a percent number e.g. `42%`.
|
||
|
- [[yii\i18n\Formatter::asScientific()|scientific]] - the value is formatted as a number in scientific format e.g. `4.2E4`.
|
||
|
- [[yii\i18n\Formatter::asCurrency()|currency]] - the value is formatted as a currency value e.g. `£420.00`.
|
||
10 years ago
|
Note that for this function to work properly, the locale needs to include a country part e.g. `en_GB` or `en_US` because language only
|
||
|
would be ambiguous in this case.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asSize()|size]] - the value that is a number of bytes is formatted as a human readable size e.g. `410 kibibytes`.
|
||
|
- [[yii\i18n\Formatter::asShortSize()|shortSize]] - is the short version of [[yii\i18n\Formatter::asSize()|size]], e.g. `410 KiB`.
|
||
|
|
||
|
The format for number formatting can be adjusted using the [[yii\i18n\Formatter::decimalSeparator|decimalSeparator]] and
|
||
|
[[yii\i18n\Formatter::thousandSeparator|thousandSeparator]] which are set by default according to the locale.
|
||
|
|
||
|
For more advanced configuration, [[yii\i18n\Formatter::numberFormatterOptions]] and [[yii\i18n\Formatter::numberFormatterTextOptions]]
|
||
10 years ago
|
can be used to configure the internally used [NumberFormatter class](http://php.net/manual/en/class.numberformatter.php)
|
||
10 years ago
|
|
||
10 years ago
|
For example, to adjust the maximum and minimum value of fraction digits, you can configure [[yii\i18n\Formatter::numberFormatterOptions]] property like the following:
|
||
10 years ago
|
|
||
10 years ago
|
```php
|
||
10 years ago
|
'numberFormatterOptions' => [
|
||
10 years ago
|
NumberFormatter::MIN_FRACTION_DIGITS => 0,
|
||
|
NumberFormatter::MAX_FRACTION_DIGITS => 2,
|
||
|
]
|
||
|
```
|
||
10 years ago
|
|
||
10 years ago
|
Other formatters <span id="other"></span>
|
||
10 years ago
|
----------------
|
||
10 years ago
|
|
||
10 years ago
|
In addition to date, time and number formatting, Yii provides a set of other useful formatters for different situations:
|
||
10 years ago
|
|
||
10 years ago
|
- [[yii\i18n\Formatter::asRaw()|raw]] - the value is outputted as is, this is a pseudo-formatter that has no effect except that
|
||
|
`null` values will be formatted using [[nullDisplay]].
|
||
|
- [[yii\i18n\Formatter::asText()|text]] - the value is HTML-encoded.
|
||
|
This is the default format used by the [GridView DataColumn](output-data-widgets.md#data-column).
|
||
|
- [[yii\i18n\Formatter::asNtext()|ntext]] - the value is formatted as an HTML-encoded plain text with newlines converted
|
||
10 years ago
|
into line breaks.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asParagraphs()|paragraphs]] - the value is formatted as HTML-encoded text paragraphs wrapped
|
||
10 years ago
|
into `<p>` tags.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asHtml()|html]] - the value is purified using [[HtmlPurifier]] to avoid XSS attacks. You can
|
||
10 years ago
|
pass additional options such as `['html', ['Attr.AllowedFrameTargets' => ['_blank']]]`.
|
||
10 years ago
|
- [[yii\i18n\Formatter::asEmail()|email]] - the value is formatted as a `mailto`-link.
|
||
|
- [[yii\i18n\Formatter::asImage()|image]] - the value is formatted as an image tag.
|
||
|
- [[yii\i18n\Formatter::asUrl()|url]] - the value is formatted as a hyperlink.
|
||
|
- [[yii\i18n\Formatter::asBoolean()|boolean]] - the value is formatted as a boolean. By default `true` is rendered
|
||
10 years ago
|
as `Yes` and `false` as `No`, translated to the current application language. You can adjust this by configuring
|
||
10 years ago
|
the [[yii\i18n\Formatter::booleanFormat]] property.
|
||
10 years ago
|
|
||
10 years ago
|
`null`-values <span id="null-values"></span>
|
||
10 years ago
|
-------------
|
||
|
|
||
10 years ago
|
For values that are `null` in PHP, the formatter class will print a placeholder instead of an empty string which
|
||
10 years ago
|
defaults to `(not set)` translated to the current application language. You can configure the
|
||
10 years ago
|
[[yii\i18n\Formatter::nullDisplay|nullDisplay]] property to set a custom placeholder.
|
||
10 years ago
|
If you do not want special handling for `null` values, you can set [[yii\i18n\Formatter::nullDisplay|nullDisplay]] to `null`.
|