Skip to content

Document that DateInterval addition depends on how the interval was created #5830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lacatoire merged 4 commits into from
Sep 3, 2026
Merged

Document that DateInterval addition depends on how the interval was created #5830

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
20b6fee
Unwrap examples and lists from para in the DateTime reference
lacatoire Sep 3, 2026
261bbc4
Document that DateInterval addition depends on how the interval was made
lacatoire Sep 3, 2026
4cbef98
Scope the elapsed-time wording to the time part of the interval
lacatoire Sep 3, 2026
6fd4260
Drop weeks from the list of date components
lacatoire Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions reference/datetime/dateinterval.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,20 @@
is by calculating the difference between two date/time objects through
<methodname>DateTimeInterface::diff</methodname>.
</para>
<simpara>
How the time part of an interval, that is hours, minutes, seconds and
microseconds, is applied when the interval is added to, or subtracted
from, a date/time object depends on how the interval was created. For an
interval created with <methodname>DateInterval::__construct</methodname>
the time part covers elapsed time, whereas for an interval created with
<methodname>DateInterval::createFromDateString</methodname>, or returned
by <methodname>DateTimeInterface::diff</methodname>, it increments or
decrements the individual component values. The date part, that is years,
months and days, always increments or decrements the individual component
values. The two therefore only give a different result when a
timezone transition falls within the time part of the interval; see
<link linkend="datetime.examples-arithmetic">Date/Time Arithmetic</link>.
</simpara>
<para>
Since there is no well defined way to compare date intervals,
<classname>DateInterval</classname> instances are
Expand Down
106 changes: 55 additions & 51 deletions reference/datetime/dateinterval/createfromdatestring.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,26 +28,24 @@

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>datetime</parameter></term>
<listitem>
<para>
A date with relative parts. Specifically, the
<link linkend="datetime.formats.relative">relative formats</link> supported
by the parser used for <classname>DateTimeImmutable</classname>,
<classname>DateTime</classname>, and <function>strtotime</function>
will be used to construct the DateInterval.
</para>
<para>
To use an ISO-8601 format string like <literal>P7D</literal>, you must
use the <methodname>DateInterval::__construct</methodname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term><parameter>datetime</parameter></term>
<listitem>
<simpara>
A date with relative parts. Specifically, the
<link linkend="datetime.formats.relative">relative formats</link> supported
by the parser used for <classname>DateTimeImmutable</classname>,
<classname>DateTime</classname>, and <function>strtotime</function>
will be used to construct the DateInterval.
</simpara>
<simpara>
To use an ISO-8601 format string like <literal>P7D</literal>, you must
use the <methodname>DateInterval::__construct</methodname>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
Expand Down Expand Up @@ -110,13 +108,12 @@

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Parsing valid date intervals</title>
<programlisting role="php" annotations="non-interactive">
<example>
<title>Parsing valid date intervals</title>
<programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
// Each set of intervals is equal.
// Each set of intervals describes the same duration.
$i = new DateInterval('P1D');
$i = DateInterval::createFromDateString('1 day');

Expand All @@ -138,13 +135,23 @@ $i = DateInterval::createFromDateString('1 day + 12 hours');
$i = new DateInterval('PT3600S');
$i = DateInterval::createFromDateString('3600 seconds');
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Parsing combinations and negative intervals</title>
<programlisting role="php">
</programlisting>
</example>
<note>
<simpara>
The intervals in a set that have a time part, such as
<literal>P1DT12H</literal> and <literal>1 day + 12 hours</literal>, are
not interchangeable when they are added to a date/time object and a
timezone transition falls within that time part: for an interval created
with <methodname>DateInterval::__construct</methodname> the time part
covers elapsed time, whereas for an interval created with this method it
increments or decrements the individual component values. See
<link linkend="datetime.examples-arithmetic">Date/Time Arithmetic</link>.
</simpara>
</note>
<example>
<title>Parsing combinations and negative intervals</title>
<programlisting role="php">
<![CDATA[
<?php
$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
Expand All @@ -153,20 +160,18 @@ echo $i->format('%d %h %i'), "\n";
$i = DateInterval::createFromDateString('1 year - 10 days');
echo $i->format('%y %d'), "\n";
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
449 2 70
1 -10
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Parsing special relative date intervals</title>
<programlisting role="php">
</screen>
</example>
<example>
<title>Parsing special relative date intervals</title>
<programlisting role="php">
<![CDATA[
<?php
$i = DateInterval::createFromDateString('last day of next month');
Expand All @@ -175,9 +180,9 @@ var_dump($i);
$i = DateInterval::createFromDateString('last weekday');
var_dump($i);
]]>
</programlisting>
&example.outputs.82;
<screen role="php">
</programlisting>
&example.outputs.82;
<screen role="php">
<![CDATA[
object(DateInterval)#1 (2) {
["from_string"]=>
Expand All @@ -192,9 +197,9 @@ object(DateInterval)#2 (2) {
string(12) "last weekday"
}
]]>
</screen>
&example.outputs.8.similar;
<screen role="php">
</screen>
&example.outputs.8.similar;
<screen role="php">
<![CDATA[
object(DateInterval)#1 (16) {
["y"]=>
Expand Down Expand Up @@ -265,9 +270,8 @@ object(DateInterval)#2 (16) {
int(1)
}
]]>
</screen>
</example>
</para>
</screen>
</example>
</refsect1>

</refentry>
Expand Down
1 change: 1 addition & 0 deletions reference/datetime/datetimeimmutable/add.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@ echo $newDate2->format('Y-m-d') . "\n";
<member><function>DateTimeImmutable::sub</function></member>
<member><function>DateTimeImmutable::diff</function></member>
<member><function>DateTimeImmutable::modify</function></member>
<member><link linkend="datetime.examples-arithmetic">Date/Time Arithmetic</link></member>
</simplelist>
</refsect1>
</refentry>
Expand Down
1 change: 1 addition & 0 deletions reference/datetime/datetimeimmutable/sub.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,7 @@ echo $newDate2->format('Y-m-d') . "\n";
<member><function>DateTimeImmutable::add</function></member>
<member><function>DateTimeImmutable::diff</function></member>
<member><function>DateTimeImmutable::modify</function></member>
<member><link linkend="datetime.examples-arithmetic">Date/Time Arithmetic</link></member>
</simplelist>
</refsect1>

Expand Down
128 changes: 76 additions & 52 deletions reference/datetime/examples.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,65 +10,90 @@
The following examples show some pitfalls of Date/Time arithmetic with regard
to DST transitions and months having different numbers of days.
</para>
<para>
<example>
<title>DateTimeImmutable::add/sub add intervals which cover elapsed time</title>
<simpara>
Adding PT24H over a DST transition will appear to add 23/25 hours (for
most timezones).
</simpara>
<programlisting role="php">
<example>
<title>DateTimeImmutable::add/sub add intervals which cover elapsed time</title>
<simpara>
Adding PT24H over a DST transition will appear to add 23/25 hours (for
most timezones).
</simpara>
<programlisting role="php">
<![CDATA[
<?php
$dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->add(new DateInterval("PT3H"));
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Start: 2015-11-01 00:00:00 -04:00
End: 2015-11-01 02:00:00 -05:00
]]>
</screen>
</example>
</para>
<para>
<example>
<title>DateTimeImmutable::modify and strtotime increment or decrement individual component values</title>
<simpara>
Adding +24 hours over a DST transition will add exactly 24 hours as seen in
the date/time string (unless the start or end time is on a transition
point).
</simpara>
<programlisting role="php">
</screen>
</example>
<example>
<title>DateTimeImmutable::modify and strtotime increment or decrement individual component values</title>
<simpara>
Adding +24 hours over a DST transition will add exactly 24 hours as seen in
the date/time string (unless the start or end time is on a transition
point).
</simpara>
<programlisting role="php">
<![CDATA[
<?php
$dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->modify("+24 hours");
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Start: 2015-11-01 00:00:00 -04:00
End: 2015-11-02 00:00:00 -05:00
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Adding or subtracting times can over- or underflow dates</title>
<simpara>
Like where January 31st + 1 month will result in March 2nd (leap year) or
3rd (normal year).
</simpara>
<programlisting role="php">
</screen>
</example>
<example>
<title>DateInterval::createFromDateString creates intervals which increment or decrement component values</title>
<simpara>
<methodname>DateInterval::createFromDateString</methodname> uses the
date/time parser, and the time part of the resulting interval increments
or decrements the individual component values. For an interval created
with <methodname>DateInterval::__construct</methodname> the time part
covers elapsed time instead, so the two are not interchangeable when a
timezone transition falls within that time part. The date part is applied
the same way by both, so <literal>P1D</literal> and
<literal>1 day</literal> always give the same result.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
$dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
echo "PT24H: ", $dt->add(new DateInterval("PT24H"))->format("Y-m-d H:i:s P"), PHP_EOL;
echo "24 hours: ", $dt->add(DateInterval::createFromDateString("24 hours"))->format("Y-m-d H:i:s P"), PHP_EOL;
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Start: 2015-11-01 00:00:00 -04:00
PT24H: 2015-11-01 23:00:00 -05:00
24 hours: 2015-11-02 00:00:00 -05:00
]]>
</screen>
</example>
<example>
<title>Adding or subtracting times can over- or underflow dates</title>
<simpara>
Like where January 31st + 1 month will result in March 2nd (leap year) or
3rd (normal year).
</simpara>
<programlisting role="php">
<![CDATA[
<?php
echo "Normal year:\n"; // February has 28 days
Expand All @@ -83,9 +108,9 @@ echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->modify("+1 month");
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Normal year:
Start: 2015-01-31 00:00:00 -05:00
Expand All @@ -94,12 +119,12 @@ Leap year:
Start: 2016-01-31 00:00:00 -05:00
End: 2016-03-02 00:00:00 -05:00
]]>
</screen>
<simpara>
To get the last day of the next month (i.e. to prevent the overflow),
the <literal>last day of</literal> format is available.
</simpara>
<programlisting role="php">
</screen>
<simpara>
To get the last day of the next month (i.e. to prevent the overflow),
the <literal>last day of</literal> format is available.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
echo "Normal year:\n"; // February has 28 days
Expand All @@ -114,9 +139,9 @@ echo "Start: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
$dt = $dt->modify("last day of next month");
echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Normal year:
Start: 2015-01-31 00:00:00 -05:00
Expand All @@ -125,9 +150,8 @@ Leap year:
Start: 2016-01-31 00:00:00 -05:00
End: 2016-02-29 00:00:00 -05:00
]]>
</screen>
</example>
</para>
</screen>
</example>
</section>

</chapter>
Expand Down