20 KiB
Форматирование данных
Для форматирования вывода Yii предоставляет класс, преобразующий данные в человеко понятный формат.
yii\i18n\Formatter это класс-помощник, который зарегистрирован как
компонент приложения, по-умолчанию под именем formatter
.
Он предоставляет набор методов для форматирования таких данных как дата/время, числа и другие часто используемые в целях локализации форматы. Formatter может быть использован двумя различными способами.
-
Напрямую используя методы форматирования (все методы форматирования имеют префикс
as
):echo Yii::$app->formatter->asDate('2014-01-01', 'long'); // выведет: January 1, 2014 echo Yii::$app->formatter->asPercent(0.125, 2); // выведет: 12.50% echo Yii::$app->formatter->asEmail('cebe@example.com'); // выведет: <a href="mailto:cebe@example.com">cebe@example.com</a> echo Yii::$app->formatter->asBoolean(true); // выведет: Yes // он также умеет отображать null значения: echo Yii::$app->formatter->asDate(null); // выведет: (Not set)
-
Используя метод yii\i18n\Formatter::format() и имя формата. Этот метод также используется в виджетах на подобии yii\grid\GridView и yii\widgets\DetailView, в которых вы можете задать формат отображения данных в колонке через конфигурацию виджета.
echo Yii::$app->formatter->format('2014-01-01', 'date'); // выведет: January 1, 2014 // вы также можете использовать массивы для настроек метода форматирования: // `2` это значение для $decimals параметра метода asPercent(). echo Yii::$app->formatter->format(0.125, ['percent', 2]); // выведет: 12.50%
Все данные, отображаемые через компонент formatter, будут локализованы, если расширение PHP intl было установлено. Для этого вы можете настроить свойство yii\i18n\Formatter::locale. Если оно не было настроено, то в качестве локали будет использован yii\base\Application::language. Подробнее смотрите в разделе «интернационализация». Компонент форматирования будет выбирать корректный формат для даты и чисел в соответствии с локалью, включая имена месяцев и дней недели, переведённые на текущий язык. Форматирование дат также зависит от yii\i18n\Formatter::timeZone, которая также будет из свойства yii\base\Application::timeZone приложения, если она не была задана явно.
Например, форматирование даты, вызванное с разной локалью, отобразит разные результаты::
Yii::$app->formatter->locale = 'en-US';
echo Yii::$app->formatter->asDate('2014-01-01'); // выведет: January 1, 2014
Yii::$app->formatter->locale = 'de-DE';
echo Yii::$app->formatter->asDate('2014-01-01'); // выведет: 1. January 2014
Yii::$app->formatter->locale = 'ru-RU';
echo Yii::$app->formatter->asDate('2014-01-01'); // выведет: 1 января 2014 г.
Обратите внимание, что форматирование может различаться между различными версиями библиотеки ICU, собранных с PHP, а также на основе того установлено ли [расширение PHP intl] (http://php.net/manual/ru/book.intl.php) или нет. Таким образом, чтобы гарантировать, что ваш сайт будет одинаково отображать данные во всех окружениях рекомендуется установить расширение PHP intl во всех окружениях и проверить, что версия библиотеки ICU совпадает. См. также: Настройка PHP окружения для интернационализации.
Отметим также, что даже если установлено расширение PHP intl, форматирование даты и времени для значений года >=2038 или <=1901 на 32-ух разрядных системах будет обращаться к реализации PHP, которая не обеспечивает локализованные имена месяца и дня, потому что в этом случае intl будет использовать 32-ух битный UNIX timestamp. На 64-битной системе intl formatter будет работать во всех случаях, если, конечно, intl был установлен.
Настройка форматирования
Форматы по-умолчанию, используемые в методах форматирования, можно настраивать через свойства
yii\i18n\Formatter. Вы можете задать форматирование по-умолчанию для всего приложения, настроив
компонент formatter
в вашей конфигурации приложения. Ниже
приведён пример конфигурации. Чтобы узнать больше о доступных свойствах см. yii\i18n\Formatter
и следующим подсекциям.
'components' => [
'formatter' => [
'dateFormat' => 'dd.MM.yyyy',
'decimalSeparator' => ',',
'thousandSeparator' => ' ',
'currencyCode' => 'EUR',
],
],
Форматирование значений даты и времени
Класс форматирования предоставляет различные методы для форматирования значений даты и времени. Например:
- yii\i18n\Formatter::asDate() - значение будет отформатировано как дата, например
January 01, 2014
. - yii\i18n\Formatter::asTime() - значение будет отформатировано как время, например
14:23
. - yii\i18n\Formatter::asDatetime() - значение будет отформатировано как дата и время, например
January 01, 2014 14:23
. - yii\i18n\Formatter::asTimestamp() - значение будет отформатировано как
unix timestamp, например,
1412609982
. - yii\i18n\Formatter::asRelativeTime() - значение будет отформатировано как временной промежуток между
заданной датой и текущий временем в человеко понятном формате, например:
1 час назад
. - yii\i18n\Formatter::asDuration(): значение будет отформатировано как продолжительность в человеко понятном
формате, например
1 день, 2 минуты
.
Форматирование даты и времени для методов yii\i18n\Formatter::asDate(), yii\i18n\Formatter::asTime() и yii\i18n\Formatter::asDatetime() может быть задано глобально через конфигурацию свойств форматирования yii\i18n\Formatter::$dateFormat, yii\i18n\Formatter::$timeFormat и yii\i18n\Formatter::$datetimeFormat.
По-умолчанию, форматирование использует сокращенный формат, который интерпретируется по-разному в зависимости от активной в данный момент локали. Поэтому дата и время будут отформатированы наиболее часто используемым способом в стране и языке пользователя. Доступны 4 разных сокращенных формата:
short
в локалеen_GB
отобразит, например,06/10/2014
для даты и15:58
для времени, в то время какmedium
будет отображать6 Oct 2014
и15:58:42
соответственно,long
будет отображать6 October 2014
и15:58:42 GMT
соответственно иfull
будет отображатьMonday, 6 October 2014
и15:58:42 GMT
соответственно.
Дополнительно вы можете задать специальный формат, используя синтаксис, заданный ICU Project,
который описан в руководстве ICU по следующему адресу:
http://userguide.icu-project.org/formatparse/datetime. Также вы можете использовать синтаксис, который распознаётся
PHP-функцией date(), используя строку с префиксом php:
.
// ICU форматирование
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06
// PHP date() форматирование
echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06
Часовые пояса
Для форматирования значений даты и времени Yii будет преобразовывать их в соответствии с yii\i18n\Formatter::timeZone. Поэтому предполагается, что входные значения будут в UTC, если часовой пояс не был указан явно. По этой причине рекомендуется хранить все значения даты и времени в формате UTC, предпочтительно в виде UNIX timestamp, которая всегда в часовом поясе UTC по определению. Если входное значение находится в часовом поясе, отличном от UTC, часовой пояс должен быть указан явно, как в следующем примере:
// при условии 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
Начиная с версии 2.0.1 стало возможно настраивать часовой пояс для предполагаемых timestamp, которые не включают в себя часовой пояс, как во втором примере в коде выше. Вы можете задать yii\i18n\Formatter::defaultTimeZone часовым поясом, который вы используете для хранения данных.
Note: Поскольку часовые пояса являются субъектом ответственности правительств по всему миру и могут часто меняться, это значит, что вы, вероятно, не имеете самую свежую информацию в базе данных часовых поясов, установленной на вашем сервере. Вы можете обратиться к ICU руководству для получения подробностей об обновлении базы данных часовых поясов. См. также: Настройка вашего PHP окружения для интернационализации.
Форматирование чисел
Для форматирования числовых значений класс форматирования предоставляет следующие методы:
- yii\i18n\Formatter::asInteger() - значение будет отформатировано как целое число, например
42
. - yii\i18n\Formatter::asDecimal() - значение будет отформатировано как дробное число, состоящее из целого и
дробной части, например:
2,542.123
или2.542,123
. - yii\i18n\Formatter::asPercent() - значение будет отформатировано как процентное значение, например
42%
. - yii\i18n\Formatter::asScientific() - значение будет отформатировано в научном формате, например:
4.2E4
. - yii\i18n\Formatter::asCurrency() - значение будет отформатировано в денежном формате, например:
£420.00
. Обратите внимание, чтобы эта функция работала правильно, локаль должна включать в себя часть со страной, например:en_GB
илиen_US
потому что только язык будет неоднозначным в этом случае. - yii\i18n\Formatter::asSize() - значение будет отформатировано как количество байт в человеко понятном формате,
например:
410 kibibytes
. - yii\i18n\Formatter::asShortSize() - сокращённая версия yii\i18n\Formatter::asSize(), например:
410 KiB
.
Форматирование чисел может быть скорректирована с помощью yii\i18n\Formatter::decimalSeparator и yii\i18n\Formatter::thousandSeparator, которые были заданы в соответствии с локалью.
Для более сложной конфигурации, yii\i18n\Formatter::numberFormatterOptions и yii\i18n\Formatter::numberFormatterTextOptions могут быть использованы для настройки внутренне используемого класса NumberFormatter
Например, чтобы настроить максимальное и минимальное количество знаков после запятой, вы можете настроить свойство yii\i18n\Formatter::numberFormatterOptions как в примере ниже:
'numberFormatterOptions' => [
NumberFormatter::MIN_FRACTION_DIGITS => 0,
NumberFormatter::MAX_FRACTION_DIGITS => 2,
]
Остальное форматирование
Кроме форматирование даты, времени и чисел, Yii предоставляет набор других полезных средств форматирования для различных ситуаций:
- yii\i18n\Formatter::asRaw() - значением будет отображено как есть, это псевдо-форматирование, которое не даёт
никакого эффекта,
кроме значений
null
, которые будет отформатированы в соответствии с nullDisplay. - yii\i18n\Formatter::asText() - значением будет экранированный от HTML текст. Это формат по-умолчанию, используемый в GridView DataColumn.
- yii\i18n\Formatter::asNtext() - значением будет экранированный от HTML текст с новыми строками, сконвертированными в разрывы строк.
- yii\i18n\Formatter::asParagraphs() - значением будет экранированный от HTML текст с параграфами,
обрамлёнными в
<p>
теги. - yii\i18n\Formatter::asHtml() - значение будет очищено, используя HtmlPurifier с целью предотвратить XSS
атаки. Вы можете задать дополнительные параметры, такие как
['html', ['Attr.AllowedFrameTargets' => ['_blank']]]
. - yii\i18n\Formatter::asEmail() - значение будет отформатировано как ссылка
mailto
. - yii\i18n\Formatter::asImage() - значение будет отформатировано как тег картинки.
- yii\i18n\Formatter::asUrl() - значение будет отформатировано как ссылка .
- [[yii\i18n\Formatter::asBoolean()|boolean]] - значение форматируется как логическое. По-умолчанию
true
будет отображено какYes
иfalse
какNo
, переведенное на язык приложения. Вы можете настроить это через свойство [[yii\i18n\Formatter::booleanFormat]].
null
значения
Для значений null
в PHP, класс форматирования будет отображать вместо пустой строки маркер, по-умолчанию это
(not set)
, переведенный на язык приложения. Вы можете настроить свойство [[yii\i18n\Formatter::nullDisplay|nullDisplay]]
для установки собственного маркера. Если вы не хотите обрабатывать null
значения, то установите свойство
[[yii\i18n\Formatter::nullDisplay|nullDisplay]] в null
.