Форматирование данных

Для отображения данных в более удобочитаемом формате для пользователей, вы можете отформатировать их с помощью formatter компонента приложения. По умолчанию форматировщик реализован с помощью yii\i18n\Formatter, который предоставляет набор методов для форматирования данных как дат/времени, чисел, валют и других часто используемых форматов. Вы можете использовать форматировщик следующим образом,

$formatter = \Yii::$app->formatter;

// output: January 1, 2014
echo $formatter->asDate('2014-01-01', 'long');
 
// output: 12.50%
echo $formatter->asPercent(0.125, 2);
 
// output: <a href="mailto:cebe@example.com">cebe@example.com</a>
echo $formatter->asEmail('cebe@example.com'); 

// output: Yes
echo $formatter->asBoolean(true); 
// it also handles display of null values:

// output: (not set)
echo $formatter->asDate(null); 

Как видите, все эти методы имеют имена asXyz(), где Xyz обозначает поддерживаемый формат. В качестве альтернативы, вы можете форматировать данные с помощью универсального метода format(), который позволяет программно управлять желаемым форматом и часто используется виджетами, такими как yii\grid\GridView и yii\widgets\DetailView. Например,

// output: January 1, 2014
echo Yii::$app->formatter->format('2014-01-01', 'date'); 

// 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.
// output: 12.50%
echo Yii::$app->formatter->format(0.125, ['percent', 2]); 

Примечание: Компонент форматировщика предназначен для форматирования значений для отображения конечному пользователю. Если вы хотите преобразовать пользовательский ввод в формат, читаемый машиной, или просто отформатировать дату в формате, читаемом машиной, форматировщик — не подходящий инструмент. Для преобразования пользовательского ввода для значений дат и чисел используйте соответственно yii\validators\DateValidator и yii\validators\NumberValidator. Для простого преобразования между машиночитаемыми форматами дат и времени достаточно функции PHP date().

Настройка Форматировщика

Вы можете настроить правила форматирования, настроив компонент formatter в конфигурации приложения. Например,

return [
    'components' => [
        'formatter' => [
            'dateFormat' => 'dd.MM.yyyy',
            'decimalSeparator' => ',',
            'thousandSeparator' => ' ',
            'currencyCode' => 'EUR',
       ],
    ],
];

Обратитесь к yii\i18n\Formatter за свойствами, которые можно настроить.

Форматирование дат и времени

Форматировщик поддерживает следующие форматы вывода, относящиеся к датам и времени:

• дата: значение форматируется как дата, например January 01, 2014.
• время: значение форматируется как время, например 14:23.
• дата и время: значение форматируется как дата и время, например January 01, 2014 14:23.
• метка времени: значение форматируется как временная метка Unix, например 1412609982.
• относительное время: значение форматируется как временной интервал между датой и текущим временем в удобочитаемой форме, например 1 hour ago.
• продолжительность: значение форматируется как продолжительность в удобочитаемой форме. например 1 day, 2 minutes.

Значения по умолчанию для дат и времени, используемые для методов date, time и datetime, можно настроить глобально, настроив
dateFormat, timeFormat и datetimeFormat.

Вы можете указать форматы дат и времени, используя синтаксис ICU. Вы также можете использовать синтаксис PHP date() с префиксом php: для различения его от синтаксиса ICU. Например,

// 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

Информация: Некоторые буквы синтаксиса формата PHP не поддерживаются ICU, а значит расширением intl PHP и не могут использоваться в форматировщике Yii. Большинство из них (w, t, L, B, u, I, Z) не очень полезны для форматирования дат, а используются при выполнении математических операций с датами. S и U могут быть полезны. Их поведение можно достичь следующим образом:

• для S, что является английским порядковым суффиксом для дня месяца (например, st, nd, rd или th.), можно использовать следующее замещение:

  $f = Yii::$app->formatter;
  $d = $f->asOrdinal($f->asDate('2017-05-15', 'php:j'));
  echo "On the $d day of the month.";  // prints "On the 15th day of the month."
  

• для U, эпохи Unix, можно использовать формат timestamp.

При работе с приложениями, которые должны поддерживать несколько языков, часто необходимо указывать разные форматы дат и времени для разных языковых окружений. Чтобы упростить эту задачу, вы можете использовать сокращения форматов (например, long, short). Форматировщик преобразует сокращение формата в соответствующий формат в соответствии с активной локальностью. Поддерживаются следующие сокращения форматов (в примерах предполагается, что en_GB является активной локалью):

• short: выведет 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.

Начиная с версии 2.0.7, также возможно форматировать даты в разных календарных системах. Обратитесь к документации API форматировщиков $calendar для получения информации о настройке другого календаря.

Часовые пояса

При форматировании значений дат и времени Yii преобразует их в целевой часовой пояс. Предполагается, что форматируемое значение находится в UTC, если не указан часовой пояс или вы не настроили yii\i18n\Formatter::$defaultTimeZone.

В следующих примерах предполагается, что целевой часовой пояс установлен как Europe/Berlin.

// formatting a UNIX timestamp as a time
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00

// formatting a datetime string (in UTC) as a time 
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00

// formatting a datetime string (in CEST) as a time
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00

Примечание: Поскольку часовые пояса зависят от правил, установленных правительствами по всему миру, и могут часто изменяться, вероятно, у вас нет последней информации в базе данных часовых поясов, установленной на вашем компьютере. Подробности об обновлении базы данных часовых поясов см. в руководстве ICU. Также прочтите Настройка вашей среды PHP для интернационализации.

Форматирование чисел

Форматировщик поддерживает следующие форматы вывода, относящиеся к числам:

• целое число: значение форматируется как целое число, например 42.
• десятичное число: значение форматируется как десятичное число с учетом десятичных и разделителей тысяч, например 2,542.123 или 2.542,123.
• процент: значение форматируется как процентное число, например 42%.
• научный: значение форматируется как число в научном формате, например 4.2E4.
• валюта: значение форматируется как значение валюты, например £420.00. Обратите внимание, что для правильной работы этой функции, локаль должна включать часть страны, например en_GB или en_US, поскольку только язык в этом случае был бы неоднозначным.
• размер: значение, которое является количеством байтов, форматируется как удобочитаемый размер, например 410 kibibytes.
• краткий размер: короткая версия размера, например 410 KiB.

Формат для форматирования чисел может быть изменен с помощью decimalSeparator и 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 также поддерживает другие часто используемые форматы, включая

• raw: значение выводится как есть, это псевдо-форматировщик, не имеющий эффекта, за исключением того, что значения null будут отформатированы с помощью nullDisplay.
• text: значение кодируется в HTML. Это формат по умолчанию, используемый в GridView DataColumn.
• ntext: значение форматируется как HTML-кодированный простой текст с новой строкой, преобразуемой в разрыв строки.
• paragraphs: значение форматируется как HTML-кодированные абзацы текста, заключённые в <p> теги.
• html: значение очищается с помощью HtmlPurifier, чтобы избежать атак XSS. Вы можете передать дополнительные параметры, такие как ['html', ['Attr.AllowedFrameTargets' => ['_blank']]].
• email: значение форматируется как mailto-ссылка.
• image: значение форматируется как тег изображения.
• url: значение форматируется как гиперссылка.
• boolean: значение форматируется как булево. По умолчанию true отображается как Yes и false как No, переведенные на язык текущего приложения. Вы можете настроить это, настроив свойство yii\i18n\Formatter::$booleanFormat.

Значения NULL

Значения NULL форматируются особым образом. Вместо отображения пустой строки, форматировщик преобразует его в предопределённую строку, которая по умолчанию равна (not set) и переведена на язык текущего приложения. Вы можете настроить свойство nullDisplay для настройки этой строки.

Локализация формата данных

Как уже упоминалось, форматировщик может использовать текущий активный locale, чтобы определить, как отформатировать значение, подходящее для целевой страны/региона. Например, одно и то же значение даты может быть отформатировано по-разному для разных локалей:

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 г.

По умолчанию текущий активный locale определяется значением yii\base\Application::$language. Вы можете переопределить его, явно установив свойство yii\i18n\Formatter::$locale.

Примечание: Форматировщик Yii полагается на расширение PHP intl для поддержки локализованного форматирования данных. Поскольку разные версии библиотеки ICU, скомпилированной с PHP, могут давать разные результаты форматирования, рекомендуется использовать одну и ту же версию ICU для всех ваших сред. Для получения более подробной информации, обратитесь к Настройка вашей PHP среды для интернационализации.

Если расширение intl не установлено, данные не будут локализованы.

Обратите внимание, что значения даты, предшествующие 1901 году или последующие 2038 году, не будут локализованы на 32-битных системах, даже если расширение intl установлено. Это связано с тем, что в этом случае ICU использует 32-битные UNIX-метки времени для значений даты.