Обработка даты и времени является важной функцией программного обеспечения, а класс \IPS\DateTime предоставляет несколько методов, которые помогают надежно обрабатывать даты и время. Важно отметить, что класс \IPS\DateTime расширяет встроенный PHP DateTime класс, поэтому все общие методы PHP для работы с датами и временем также доступны через этот интерфейс.
Дата и время представлены в базе данных в виде UNIX-времени (timestamp). Однако, когда вы показываете дату пользователю, нам нужно преобразовать UNIX-время в удобную для чтения дату и время, локализованные в часовом поясе пользователя. Для этой цели можно использовать статический метод ts():
$time = \IPS\DateTime::ts( $timestamp );
Вы также можете использовать статический метод create() для создания нового экземпляра datetime (который будет по умолчанию использовать текущую дату/время).
$time = \IPS\DateTime::create();
Основные методы, которые вы будете использовать для отображения даты и/или времени, следующие:
/* Показывает время и дату в часовом поясе пользователя */
print (string) $time;
Магический метод __toString() автоматически позаботится о преобразованиях часового пояса и т.д.
/* Вывод HTML тега <time> HTML с отображением относительного времени */ print $time->html( TRUE, FALSE, NULL );
Первый параметр определяет, должна ли дата/время быть в формате capitalize (первый символ каждого слова будет заглавным; остальные символы свой вид не меняют) или нет (установите его в значение FALSE, если время будет использоваться в середине предложения, например), а второй параметр определяет, будет ли использоваться 'короткая' версия дата/время, даже не на мобильном устройстве (например 1д вместо 1 день). Последний параметр позволяет переопределить пользователя или язык для форматирования времени.
/* Показывать только дату */
print $time->localeDate();
/* Показывать только время - первый параметр указывает, следует ли возвращать секунды, а второй параметр указывает, следует ли возвращать минуты */
print $time->localeTime( TRUE, TRUE );
/* Возвращает только месяц и день, без указания года (или времени)
print $time->dayAndMonth();
/* Возвращает дату с 4-х значным годом */
print $time->fullYearLocaleDate();
/* Форматирует относительную дату/время */
print $time->relative( \IPS\DateTime::RELATIVE_FORMAT_NORMAL );
Для метода relative() распознаются следующие константы:
- RELATIVE_FORMAT_NORMAL: Вчера в 2 часа.
- RELATIVE_FORMAT_LOWER: вчера в 2 часа (например "Изменено вчера в 2 часа").
- RELATIVE_FORMAT_SHORT: 1д (для мобильных устройств).
Если вам нужно использовать полностью настраиваемый формат, вы можете использовать метод strFormat(). Хотя класс DateTime в PHP уже имеет встроенный метод format(), но он не понимает локали, поэтому используется метод strFormat() (который принимает любой формат, принятый strftime в PHP).
print $time->strFormat( '%B' );
Наконец, есть некоторые стандартизированные форматы, которые поддерживаются что называется "из коробки", в первую очередь полезны, когда спецификации требуют, чтобы даты были отформатированы определенным образом (например, RSS):
print $time->rfc3339(); // 2017-06-06T11:00:00Z
print $time->rfc1123(); // Вторник, 6 Июня 2017 11:00:00 GMT
Важно помнить при кешировании данных, что даты и время должны быть локализованы на основе текущего часового пояса пользователя (который определяется автоматически). По этой причине вы не должны кэшировать отформатированные даты и время, но можете форматировать при отображении.
Наконец, существует плагин шаблона "datetime", который можно использовать для автоматического форматирования дат и времени в шаблонах.
{datetime="$timestamp"}
Это отобразит локализованную дату и время из вызова __toString(). Дополнительные атрибуты, поддерживаемые этим плагином:
- dateonly: Вернуть только дату.
- norelative: Не возвращать относительную дату.
- lowercase: Вернуть дату в нижнем регистре.
- short: Вернуть короткую форму даты.