Yii фреймворк форматирование данных

Чтобы отображать данные в более читаемом формате для пользователей, вы можете отформатировать их с помощью компонента приложения 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]);

Настройка форматирования

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

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

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

formatter поддерживает следующие выходные форматы, связанные с датой и временем:

date: значение отформатировано как дата, например. 01 января 2014 года.
time: значение отформатировано как время, например. 14:23.
datetime:значение отформатировано как дата и время, например. 01 января 2014 г. 14:23.
relativeTime: значение форматируется как временной интервал между датой и теперь в удобочитаемой форме человека, например. 1 час назад.
duration: значение форматируется как продолжительность в удобочитаемом формате. например 1 день, 2 минуты.

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

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

short: выведет 06/10/2014 for date and 15:58 for time;
medium: выведет 6 Oct 2014 and 15:58:42;
long: выведет 6 October 2014 and 15:58:42 GMT;
full: выведет Monday, 6 October 2014 and 15:58:42 GMT.

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

При форматировании значений даты и времени 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

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

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

integer: значение отформатировано как целое число, например. 42.
decimal: значение отформатировано как десятичное число с учетом десятичной и тысячи разделителей, например. 2,542,123 или 2,542,123.
percent: значение отформатировано как процентное число, например. 42%.
scientific: значение отформатировано как число в научном формате, например. 4.2E4.
currency: значение отформатировано как значение валюты, например. 420,00 фунтов стерлингов. Обратите внимание, что для правильной работы этой функции языковой стандарт должен содержать элемент country, например. En_GB или en_US, поскольку в этом случае язык будет только двусмысленным.
size: значение, которое является числом байтов, отформатировано как человеческий считываемый размер, например. 410 килобайт.
shortSize: короткая версия размера, например. 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-link.
image: значение форматируется как тег изображения.
url: значение форматируется как гиперссылка.
boolean: значение форматируется как логическое значение. По умолчанию true передается как Yes, а false - No, переведенный на текущий язык приложения. Это можно настроить, настроив свойство yii\i18n\Formatter::$booleanFormat.

Нулевые значения

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

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

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

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

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

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