PHP date_interval_create_from_date_string() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Date/Time

Definition

In PHP, date_interval_create_from_date_string() builds a DateInterval object from a plain-English text like "3 days" or "1 year 2 months".

It is the procedural name for DateInterval::createFromDateString(). The interval can then be used with date_add(), date_sub(), or the add() and sub() methods.

Syntax

Call date_interval_create_from_date_string() with the values you need. Start with this line.

PHP
$interval = date_interval_create_from_date_string("3 days");
CallWhat it does
date_interval_create_from_date_string("3 days")Returns a DateInterval where d is 3.
date_interval_create_from_date_string("1 year 2 months")Returns a DateInterval with y set to 1 and m set to 2.
date_interval_create_from_date_string("2 weeks")Returns a DateInterval where d is 14, because weeks become days.

This is a friendly alternative to ISO strings such as P3D. Both give you a DateInterval. If the text cannot be understood, the function returns false (and PHP 8.3 and later also shows a warning), so check the result before you use it.

Library declarations
PHP
date_interval_create_from_date_string(string $datetime): DateInterval|false

Parameters

ParameterDescription
datetimeRequired. A relative date text such as "3 days", "1 month", or "2 weeks 3 days".

Return Value

Return ValueDescription
DateIntervalA new DateInterval object built from the text.
falseReturned when the text cannot be parsed.

PHP Examples

Example 1 — Create and Use an Interval

Turn the text 1 year 2 months 3 days into a DateInterval and read its parts.

PHP
<?php
$interval = date_interval_create_from_date_string("1 year 2 months 3 days");

echo "Years: ", $interval->y, PHP_EOL;
echo "Months: ", $interval->m, PHP_EOL;
echo "Days: ", $interval->d, PHP_EOL;

How It Works

  1. The text describes three units: a year, two months, and three days.
  2. date_interval_create_from_date_string() reads the text and returns a DateInterval object.
  3. The y, m, and d properties hold each part of the interval.
  4. Each value is printed on its own line.

Example 2 — Weeks and Invalid Text

Weeks are turned into days, and text PHP cannot understand gives false.

PHP
<?php
$interval = date_interval_create_from_date_string("2 weeks 3 days");
echo "Days: ", $interval->d, PHP_EOL;

$bad = @date_interval_create_from_date_string("banana");
var_dump($bad);

How It Works

  1. A DateInterval has no weeks property, so 2 weeks becomes 14 days.
  2. 14 days plus 3 more days gives d = 17.
  3. "banana" is not a date text, so the function returns false.
  4. The @ sign hides the warning that PHP 8. 3 and later would show. In real code, check the result instead of hiding problems.

Example 3 — Add the Interval to a Date

Use the interval with DateTimeImmutable so the original date stays unchanged.

PHP
<?php
$interval = date_interval_create_from_date_string("10 days");

$start = new DateTimeImmutable("2024-12-25");
$end = $start->add($interval);

echo "Start: ", $start->format("Y-m-d"), PHP_EOL;
echo "End: ", $end->format("Y-m-d"), PHP_EOL;

How It Works

  1. Create an interval of 10 days from text.
  2. Create a DateTimeImmutable for 25 December 2024.
  3. add() returns a new object. The original $start is not changed.
  4. Ten days after December 25 is January 4 of the next year.

Frequently Asked Questions

It creates a DateInterval object from a readable text such as "3 days" or "1 year 2 months". You can then add or subtract that interval from a date.
new DateInterval() needs an ISO 8601 duration like P3D. date_interval_create_from_date_string() accepts everyday text like "3 days". Both return a DateInterval.
Yes. If PHP cannot parse the text, it returns false. PHP 8.3 and later also emits a warning, so always check the result before using it.
The days property is only filled when an interval comes from date_diff(). Intervals created from text or ISO strings keep it as false, so use the d, m, and y properties instead.
Yes. It is the procedural alias of the static method DateInterval::createFromDateString(), and both give the same result.

Next: date_interval_format()

date_interval_format() turns a DateInterval object into a readable string using format cod.

date_interval_format() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful