date_interval_create_from_date_string()

Что такое date_interval_create_from_date_string()?

Функция date_interval_create_from_date_string() — это встроенная функция PHP, которая создаёт объект DateInterval из человекочитаемой строки относительного времени, например '1 day' или '2 weeks 3 hours'. Она является процедурным псевдонимом статического метода DateInterval::createFromDateString() — оба ведут себя одинаково.

На этой странице рассматриваются сигнатура функции, типы принимаемых строк, возвращаемое значение, важное устаревание в PHP 8.2, а также примеры добавления и форматирования интервалов.

Устаревание: date_interval_create_from_date_string() была объявлена устаревшей в PHP 8.2 и планируется к удалению в будущей версии. В новом коде предпочитайте конструктор DateInterval с ISO-8601 строкой длительности (например, new DateInterval('P1D')). См. раздел Миграция ниже.

Синтаксис

date_interval_create_from_date_string(string $datetime): DateInterval|false

Параметры

• $datetime — Строка относительного времени, того же формата, который понимает strtotime(). Используются только относительные части; абсолютные части (явная дата или время) игнорируются.

Возвращаемое значение

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

Как это работает?

Функция передаёт строку через тот же анализатор, что и strtotime(), сохраняя только относительные части. Полезные форматы:

Ведущий минус (например, '-1 week') сохраняет отрицательное значение непосредственно в соответствующем свойстве (здесь d становится -7), поэтому добавление такого интервала к дате сдвигает её назад во времени.

Базовое использование

<?php

$interval = date_interval_create_from_date_string('1 day');
var_dump($interval->d); // int(1)

Здесь мы создаём DateInterval, представляющий промежуток в один день; его свойство d (дни) равно 1.

Примеры

Пример 1: Добавление интервала к дате

В этом примере создаётся интервал в один день и добавляется к объекту DateTime с помощью DateTime::add():

Вывод:

2023-03-04

Пример 2: Форматирование интервала

В этом примере создаётся интервал в один месяц и выводится с помощью DateInterval::format(). Обратите внимание, что %m не дополняется нулями — используйте %M, если нужен ведущий ноль:

Вывод:

1 months

Пример 3: Защита от возврата false

Если строка не содержит относительных частей, функция возвращает false. Всегда выполняйте проверку перед использованием результата:

<?php

$interval = date_interval_create_from_date_string('not an interval');

if ($interval === false) {
    echo "Could not parse the interval.";
} else {
    echo $interval->format('%d days');
}

Вывод:

Could not parse the interval.

Миграция от функции

Поскольку функция является устаревшей, в новом коде предпочитайте конструктор DateInterval. Он принимает ISO-8601 строку длительности: P начинает период, а T отделяет часть даты от части времени.

<?php

// Deprecated:
$old = date_interval_create_from_date_string('1 day');

// Recommended replacement:
$new = new DateInterval('P1D'); // P = period, 1D = 1 day

echo $new->format('%d day'); // 1 day

Вывод:

1 day

Типичные преобразования: '1 day' → P1D, '2 weeks' → P14D, '1 month' → P1M, '2 hours 30 minutes' → PT2H30M.

Советы по производительности

• Создавайте интервал один раз и переиспользуйте его; избегайте повторного создания одного и того же DateInterval внутри тесных циклов.
• Разбор строки относительного времени требует немного больше ресурсов, чем конструктор, поэтому предпочитайте new DateInterval('P1D'), когда длительность фиксирована и известна заранее.

Смотрите также

• date_interval_format() — форматирование DateInterval для вывода.
• date_add() — добавление интервала к дате.
• date_diff() — получение DateInterval между двумя датами.
• strtotime() — анализатор относительного времени, на котором основана эта функция.

Заключение

date_interval_create_from_date_string() преобразует строку относительного времени в DateInterval, возвращая false, если строка не поддаётся разбору. Функция была объявлена устаревшей в PHP 8.2, поэтому в новом коде предпочитайте конструктор DateInterval с ISO-8601 длительностью (new DateInterval('P1D')). Когда вы всё же используете её, всегда проверяйте возвращаемое значение перед использованием результирующего объекта.

Практика