Времена и даты

CodeIgniter предоставляет полностью локализованный, неизменяемый класс даты/времени, построенный на объекте DateTime PHP, но использующий возможности расширения Intl для преобразования времени между часовыми поясами и правильного отображения вывода для разных локалей. Этот класс — класс Time и находится в пространстве имен CodeIgniter\I18n.

• Инициализация
• Отображение значения
• Работа с отдельными значениями

Инициализация

Существует несколько способов создания нового экземпляра Time. Первый — просто создать новый экземпляр, как любой другой класс. В этом случае можно передать строку, представляющую желаемое время. Это может быть любая строка, которую функция strtotime PHP может разобрать:

use CodeIgniter\I18n\Time;

$myTime = new Time('+3 week');
$myTime = new Time('now');

Вы можете передать строки, представляющие часовой пояс и локаль во втором и третьем параметрах соответственно. Часовые пояса могут быть любыми, поддерживаемыми классом DateTimeZone PHP. Локаль может быть любой, поддерживаемой классом Locale PHP. Если часовой пояс или локаль не указаны, будут использоваться значения по умолчанию приложения.

$myTime = new Time('now', 'America/Chicago', 'en_US');

now()

Класс Time имеет несколько вспомогательных методов для инициализации класса. Первый из них — метод now(), который возвращает новый экземпляр, установленный на текущее время. Вы можете передать строки, представляющие часовой пояс и локаль во втором и третьем параметрах соответственно. Если часовой пояс или локаль не указаны, будут использоваться значения по умолчанию приложения.

$myTime = Time::now('America/Chicago', 'en_US');

parse()

Этот вспомогательный метод является статической версией конструктора по умолчанию. Он принимает строку, приемлемую для конструктора DateTime, в качестве первого параметра, часовой пояс — в качестве второго параметра, а локаль — в качестве третьего параметра.:

$myTime = Time::parse('next Tuesday', 'America/Chicago', 'en_US');

today()

Возвращает новый экземпляр с датой, установленной на текущую дату, и временем, установленным на полночь. Принимает строки для часового пояса и локали в первом и втором параметрах:

$myTime = Time::today('America/Chicago', 'en_US');

yesterday()

Возвращает новый экземпляр с датой, установленной на вчерашнюю дату, и временем, установленным на полночь. Принимает строки для часового пояса и локали в первом и втором параметрах:

$myTime = Time::yesterday('America/Chicago', 'en_US');

tomorrow()

Возвращает новый экземпляр с датой, установленной на завтрашнюю дату, и временем, установленным на полночь. Принимает строки для часового пояса и локали в первом и втором параметрах:

$myTime = Time::tomorrow('America/Chicago', 'en_US');

createFromDate()

Принимая отдельные значения для года, месяца и дня, вернет новый экземпляр. Если какой-либо из этих параметров не указан, будет использоваться текущее значение для заполнения. Принимает строки для часового пояса и локали в четвёртом и пятом параметрах:

$today       = Time::createFromDate(); // Uses current year, month, and day
$anniversary = Time::createFromDate(2018); // Uses current month and day
$date        = Time::createFromDate(2018, 3, 15, 'America/Chicago', 'en_US');

createFromTime()

Как createFromDate, но только для часов, минут и секунд. Использует текущий день для даты экземпляра Time. Принимает строки для часового пояса и локали в четвёртом и пятом параметрах:

$lunch  = Time::createFromTime(11, 30); // 11:30 am today
$dinner = Time::createFromTime(18, 00, 00); // 6:00 pm today
$time   = Time::createFromTime($hour, $minutes, $seconds, $timezone, $locale);

create()

Комбинация предыдущих двух методов, принимает год, месяц, день, час, минуты и секунды в качестве отдельных параметров. Любое значение, не указанное явно, будет определяться по текущей дате и времени. Принимает строки для часового пояса и локали в четвёртом и пятом параметрах:

$time = Time::create($year, $month, $day, $hour, $minutes, $seconds, $timezone, $locale);

createFromFormat()

Это замена метода DateTime с тем же именем. Это позволяет установить часовой пояс одновременно и возвращает экземпляр Time, а не DateTime:

$time = Time::createFromFormat('j-M-Y', '15-Feb-2009', 'America/Chicago');

createFromTimestamp()

Этот метод принимает отметку времени Unix и, необязательно, часовой пояс и локаль для создания нового экземпляра Time:

$time = Time::createFromTimestamp(1501821586, 'America/Chicago', 'en_US');

createFromInstance()

При работе с другими библиотеками, предоставляющими экземпляр DateTime, вы можете использовать этот метод для преобразования его в экземпляр Time, необязательно задав локаль. Часовой пояс будет автоматически определен по экземпляру DateTime, переданному в параметре:

$dt   = new DateTime('now');
$time = Time::createFromInstance($dt, 'en_US');

toDateTime()

Несмотря на то, что это не инициализатор, этот метод является противоположностью методу instance, позволяя преобразовать экземпляр Time в экземпляр DateTime. Это сохраняет настройку часового пояса, но теряет локаль, поскольку DateTime не осведомлен о локалях:

$datetime = Time::toDateTime();

Отображение значения

Поскольку класс Time расширяет DateTime, вы получаете все методы вывода, которые он предоставляет, включая метод format(). Однако методы DateTime не обеспечивают локализованный результат. Класс Time предоставляет ряд вспомогательных методов для отображения локализованных версий значения.

toLocalizedString()

Это локализованная версия метода format() DateTime. Вместо использования знакомых вам значений, вы должны использовать значения, приемлемые для класса IntlDateFormatter. Полный список значений можно найти здесь.

$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toLocalizedString('MMM d, yyyy'); // March 9, 2016

toDateTimeString()

Это первый из трех вспомогательных методов для работы с IntlDateFormatter, не запоминая их значений. Он вернет строку, отформатированную так, как обычно используются столбцы datetime в базе данных (Y-m-d H:i:s):

$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateTimeString(); // 2016-03-09 12:00:00

toDateString()

Отображает только часть даты экземпляра:

$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateString(); // 2016-03-09

toTimeString()

Отображает только часть времени экземпляра:

$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toTimeString(); // 12:00:00

humanize()

Этот метод возвращает строку, отображающую разницу между текущей датой/временем и экземпляром в удобочитаемом формате, легко понимаемом. Он может создавать строки вроде «3 часа назад», «через 1 месяц» и т. д.:

// Assume current time is: March 10, 2017 (America/Chicago)
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');

echo $time->humanize(); // 1 year ago

Точное отображаемое время определяется следующим образом:

Используемый язык контролируется файлом языка, Time.php.

Работа с отдельными значениями

Объект Time предоставляет ряд методов, позволяющих получать и устанавливать отдельные элементы, такие как год, месяц, час и т. д. существующего экземпляра. Все значения, полученные с помощью следующих методов, будут полностью локализованы и учитывать локаль, с которой был создан экземпляр Time.

Все следующие getX и setX методы также могут использоваться как свойства класса. Так, любые вызовы методов, такие как getYear, также могут быть доступны через $time->year, и так далее.

Получатели

Существуют следующие основные получатели:

$time = Time::parse('August 12, 2016 4:15:23pm');

echo $time->getYear(); // 2016
echo $time->getMonth(); // 8
echo $time->getDay(); // 12
echo $time->getHour(); // 16
echo $time->getMinute(); // 15
echo $time->getSecond(); // 23

echo $time->year; // 2016
echo $time->month; // 8
echo $time->day; // 12
echo $time->hour; // 16
echo $time->minute; // 15
echo $time->second; // 23

Помимо этого, существует ряд методов, предоставляющих дополнительную информацию о дате:

$time = Time::parse('August 12, 2016 4:15:23pm');

echo $time->getDayOfWeek(); // 6 - but may vary based on locale's starting day of the week
echo $time->getDayOfYear(); // 225
echo $time->getWeekOfMonth(); // 2
echo $time->getWeekOfYear(); // 33
echo $time->getTimestamp(); // 1471018523 - UNIX timestamp
echo $time->getQuarter(); // 3

echo $time->dayOfWeek; // 6
echo $time->dayOfYear; // 225
echo $time->weekOfMonth; // 2
echo $time->weekOfYear; // 33
echo $time->timestamp; // 1471018523
echo $time->quarter; // 3

getAge()

Возвращает возраст в годах между экземпляром Time и текущим временем. Идеально подходит для проверки возраста человека на основе его даты рождения:

$time = Time::parse('5 years ago');

echo $time->getAge(); // 5
echo $time->age; // 5

getDST()

Возвращает логическое значение true/false, в зависимости от того, соблюдает ли экземпляр Time летнее время:

echo Time::createFromDate(2012, 1, 1)->getDst(); // false
echo Time::createFromDate(2012, 9, 1)->dst; // true

getLocal()

Возвращает логическое значение true, если экземпляр Time находится в том же часовом поясе, что и приложение в данный момент:

echo Time::now()->getLocal(); // true
echo Time::now('Europe/London'); // false

getUtc()

Возвращает логическое значение true, если экземпляр Time находится в часовом поясе UTC:

echo Time::now('America/Chicago')->getUtc(); // false
echo Time::now('UTC')->utc; // true

getTimezone()

Возвращает новый объект DateTimeZone, установленный в часовой пояс экземпляра Time:

$tz = Time::now()->getTimezone();
$tz = Time::now()->timezone;

echo $tz->getName();
echo $tz->getOffset();

getTimezoneName()

Возвращает полную строку часового пояса экземпляра Time:

echo Time::now('America/Chicago')->getTimezoneName(); // America/Chicago
echo Time::now('Europe/London')->timezoneName; // Europe/London

Установщики

Существуют следующие основные установщики. Если любое из установленных значений выходит за пределы диапазона, будет выброшено исключение.

$time = $time->setYear(2017);
$time = $time->setMonthNumber(4); // April
$time = $time->setMonthLongName('April');
$time = $time->setMonthShortName('Feb'); // February
$time = $time->setDay(25);
$time = $time->setHour(14); // 2:00 pm
$time = $time->setMinute(30);
$time = $time->setSecond(54);

setTimezone()

Преобразует время из текущего часового пояса в новый:

$time  = Time::parse('13 May 2020 10:00', 'America/Chicago');
$time2 = $time->setTimezone('Europe/London'); // Returns new instance converted to new timezone

echo $time->getTimezoneName(); // American/Chicago
echo $time2->getTimezoneName(); // Europe/London

echo $time->toDateTimeString(); // 2020-05-13 10:00:00
echo $time2->toDateTimeString(); // 2020-05-13 18:00:00

setTimestamp()

Возвращает новый экземпляр с датой, установленной на новую отметку времени:

$time = Time::parse('May 10, 2017', 'America/Chicago');
$time2 = $time->setTimestamp(strtotime('April 1, 2017'));

echo $time->toDateTimeString(); // 2017-05-10 00:00:00
echo $time2->toDateTimeString(); // 2017-04-01 00:00:00

Изменение значения

Следующие методы позволяют изменять дату путем добавления или вычитания значений к текущему экземпляру Time. При этом исходный экземпляр Time не изменяется, а возвращается новый.

$time = $time->addSeconds(23);
$time = $time->addMinutes(15);
$time = $time->addHours(12);
$time = $time->addDays(21);
$time = $time->addMonths(14);
$time = $time->addYears(5);

$time = $time->subSeconds(23);
$time = $time->subMinutes(15);
$time = $time->subHours(12);
$time = $time->subDays(21);
$time = $time->subMonths(14);
$time = $time->subYears(5);

Сравнение двух моментов времени

Следующие методы позволяют сравнить один экземпляр Time с другим. Все сравнения сначала преобразуются в UTC, чтобы обеспечить правильное поведение при сравнении моментов времени из разных часовых поясов.

equals()

Определяет, равен ли переданный datetime текущему экземпляру. В данном случае равенство означает, что они представляют один и тот же момент времени, и не требуется, чтобы они находились в одном часовом поясе, так как оба времени преобразуются в UTC и сравниваются таким образом:

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'Europe/London');

$time1->equals($time2); // true

Проверяемое значение может быть экземпляром Time, экземпляром DateTime или строкой с полным временем и датой, которое может быть обработано новым экземпляром DateTime. При передаче строки в качестве первого параметра можно передать строку часового пояса во втором параметре. Если часовой пояс не указан, будет использоваться системный по умолчанию:

$time1->equals('January 11, 2017 03:50:00', 'Europe/London'); // true

sameAs()

Это идентично методу equals, за исключением того, что он возвращает true только тогда, когда дата, время И часовой пояс полностью идентичны:

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'Europe/London');

$time1->sameAs($time2);    // false
$time2->sameAs('January 10, 2017 21:50:00', 'America/Chicago'); // true

isBefore()

Проверяет, является ли переданное время до текущего экземпляра. Сравнение выполняется с использованием UTC-версий обоих времен:

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'America/Chicago');

$time1->isBefore($time2); // true
$time2->isBefore($time1); // false

Проверяемое значение может быть экземпляром Time, экземпляром DateTime или строкой с полным временем и датой, которое может быть обработано новым экземпляром DateTime. При передаче строки в качестве первого параметра можно передать строку часового пояса во втором параметре. Если часовой пояс не указан, будет использоваться системный по умолчанию:

$time1->isBefore('March 15, 2013', 'America/Chicago'); // false

isAfter()

Работает точно так же, как isBefore(), но проверяет, является ли время после переданного времени:

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'America/Chicago');

$time1->isAfter($time2); // false
$time2->isAfter($time1); // true

Просмотр различий

Чтобы напрямую сравнить два времени, используйте метод difference(), который возвращает экземпляр CodeIgniter\I18n\TimeDifference. Первый параметр — это экземпляр Time, DateTime или строка с датой/временем. Если в качестве первого параметра передается строка, второй параметр может быть строкой часового пояса:

$time = Time::parse('March 10, 2017', 'America/Chicago');

$diff = $time->difference(Time::now());
$diff = $time->difference(new DateTime('July 4, 1975', 'America/Chicago');
$diff = $time->difference('July 4, 1975 13:32:05', 'America/Chicago');

После получения экземпляра TimeDifference у вас есть несколько методов, которые можно использовать для получения информации о разнице между двумя временами. Возвращаемое значение будет отрицательным, если время было в прошлом, или положительным, если оно было в будущем по сравнению с исходным временем:

$current = Time::parse('March 10, 2017', 'America/Chicago');
$test    = Time::parse('March 10, 2010', 'America/Chicago');

$diff = $current->difference($test);

echo $diff->getYears(); // -7
echo $diff->getMonths(); // -84
echo $diff->getWeeks(); // -365
echo $diff->getDays(); // -2557
echo $diff->getHours(); // -61368
echo $diff->getMinutes(); // -3682080
echo $diff->getSeconds(); // -220924800

Вы можете использовать методы getX() или получить доступ к вычисленным значениям как к свойствам:

echo $diff->years;   // -7
echo $diff->months; // -84
echo $diff->weeks; // -365
echo $diff->days; // -2557
echo $diff->hours; // -61368
echo $diff->minutes; // -3682080
echo $diff->seconds; // -220924800

humanize()

Подобно методу humanize() объекта Time, этот метод возвращает строку, отображающую разницу во времени в удобочитаемом формате, который легко понять. Он может создавать строки, такие как «3 часа назад», «через 1 месяц» и т. д. Основные различия заключаются в том, как обрабатываются очень недавние даты:

$current = Time::parse('March 10, 2017', 'America/Chicago')
$test    = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');

$diff = $current->difference($test)

echo $diff->humanize(); // 1 year ago

Точное отображаемое время определяется следующим образом:

Используемый язык контролируется файлом локализации Time.php.