date_interval_create_from_date_string()

What is date_interval_create_from_date_string()?

The date_interval_create_from_date_string() function is a built-in PHP function that builds a DateInterval object from a human-readable relative-time string such as '1 day' or '2 weeks 3 hours'. It is the procedural alias of the static method DateInterval::createFromDateString() — both behave identically.

This page covers the function's signature, what kinds of strings it accepts, the value it returns, the important PHP 8.2 deprecation, and runnable examples for adding and formatting intervals.

Deprecation: date_interval_create_from_date_string() was deprecated in PHP 8.2 and is scheduled for removal in a future version. Prefer the DateInterval constructor with an ISO-8601 duration string (for example new DateInterval('P1D')) in new code. See Migration below.

Syntax

date_interval_create_from_date_string(string $datetime): DateInterval|false

Parameters

• $datetime — A relative-time string, the same kind that strtotime() understands. Only the relative parts are used; absolute parts (an explicit date or time) are ignored.

Return value

Returns a DateInterval object on success, or false if the string contains no relative parts that can be parsed. Always check the return value before using it.

How does it work?

The function feeds the string through the same parser as strtotime() and keeps only the relative pieces. Useful formats include:

A leading minus (for example '-1 week') stores a negative value directly in the relevant property (here d becomes -7), so adding such an interval to a date moves backwards in time.

Basic usage

<?php

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

Here we create a DateInterval representing a one-day span; its d (days) property is 1.

Examples

Example 1: Adding an interval to a date

This example creates a one-day interval and adds it to a DateTime object with DateTime::add():

Output:

2023-03-04

Example 2: Formatting an interval

This example creates a one-month interval and prints it with DateInterval::format(). Note that %m is not zero-padded — use %M if you want a leading zero:

Output:

1 months

Example 3: Guarding against a false return

If the string has no relative parts, the function returns false. Always check before using the result:

<?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');
}

Output:

Could not parse the interval.

Migrating away from the function

Because the function is deprecated, prefer the DateInterval constructor in new code. It takes an ISO-8601 duration string: P starts a period, and T separates the date part from the time part.

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

Output:

1 day

Common conversions: '1 day' → P1D, '2 weeks' → P14D, '1 month' → P1M, '2 hours 30 minutes' → PT2H30M.

Performance tips

• Build an interval once and reuse it; avoid recreating the same DateInterval inside tight loops.
• Parsing a relative string is slightly more work than the constructor, so prefer new DateInterval('P1D') when the duration is fixed and known ahead of time.

See also

• date_interval_format() — format a DateInterval for display.
• date_add() — add an interval to a date.
• date_diff() — get the DateInterval between two dates.
• strtotime() — the relative-time parser this function relies on.

Conclusion

date_interval_create_from_date_string() turns a relative-time string into a DateInterval, returning false when the string can't be parsed. It was deprecated in PHP 8.2, so for new code prefer the DateInterval constructor with an ISO-8601 duration (new DateInterval('P1D')). When you do use it, always validate the return value before relying on the resulting object.

Practice