diff --git a/reference/datetime/dateinterval.xml b/reference/datetime/dateinterval.xml index 1b6fdeed4798..e42ff185aef9 100644 --- a/reference/datetime/dateinterval.xml +++ b/reference/datetime/dateinterval.xml @@ -28,6 +28,20 @@ is by calculating the difference between two date/time objects through DateTimeInterface::diff. + + 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 DateInterval::__construct + the time part covers elapsed time, whereas for an interval created with + DateInterval::createFromDateString, or returned + by DateTimeInterface::diff, 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 + Date/Time Arithmetic. + Since there is no well defined way to compare date intervals, DateInterval instances are diff --git a/reference/datetime/dateinterval/createfromdatestring.xml b/reference/datetime/dateinterval/createfromdatestring.xml index 886cac0d345b..7598a71d0395 100644 --- a/reference/datetime/dateinterval/createfromdatestring.xml +++ b/reference/datetime/dateinterval/createfromdatestring.xml @@ -28,26 +28,24 @@ &reftitle.parameters; - - - - datetime - - - A date with relative parts. Specifically, the - relative formats supported - by the parser used for DateTimeImmutable, - DateTime, and strtotime - will be used to construct the DateInterval. - - - To use an ISO-8601 format string like P7D, you must - use the DateInterval::__construct. - - - - - + + + datetime + + + A date with relative parts. Specifically, the + relative formats supported + by the parser used for DateTimeImmutable, + DateTime, and strtotime + will be used to construct the DateInterval. + + + To use an ISO-8601 format string like P7D, you must + use the DateInterval::__construct. + + + + @@ -110,13 +108,12 @@ &reftitle.examples; - - - Parsing valid date intervals - + + Parsing valid date intervals + - - - - - - Parsing combinations and negative intervals - + + + + + The intervals in a set that have a time part, such as + P1DT12H and 1 day + 12 hours, 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 DateInterval::__construct the time part + covers elapsed time, whereas for an interval created with this method it + increments or decrements the individual component values. See + Date/Time Arithmetic. + + + + Parsing combinations and negative intervals + format('%d %h %i'), "\n"; $i = DateInterval::createFromDateString('1 year - 10 days'); echo $i->format('%y %d'), "\n"; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - Parsing special relative date intervals - + + + + Parsing special relative date intervals + - - &example.outputs.82; - + + &example.outputs.82; + @@ -192,9 +197,9 @@ object(DateInterval)#2 (2) { string(12) "last weekday" } ]]> - - &example.outputs.8.similar; - + + &example.outputs.8.similar; + @@ -265,9 +270,8 @@ object(DateInterval)#2 (16) { int(1) } ]]> - - - + + diff --git a/reference/datetime/datetimeimmutable/add.xml b/reference/datetime/datetimeimmutable/add.xml index 5d2595cb0a74..7715645771b4 100644 --- a/reference/datetime/datetimeimmutable/add.xml +++ b/reference/datetime/datetimeimmutable/add.xml @@ -117,6 +117,7 @@ echo $newDate2->format('Y-m-d') . "\n"; DateTimeImmutable::sub DateTimeImmutable::diff DateTimeImmutable::modify + Date/Time Arithmetic diff --git a/reference/datetime/datetimeimmutable/sub.xml b/reference/datetime/datetimeimmutable/sub.xml index 8b4c2f66a6f4..6ed595a4fed7 100644 --- a/reference/datetime/datetimeimmutable/sub.xml +++ b/reference/datetime/datetimeimmutable/sub.xml @@ -155,6 +155,7 @@ echo $newDate2->format('Y-m-d') . "\n"; DateTimeImmutable::add DateTimeImmutable::diff DateTimeImmutable::modify + Date/Time Arithmetic diff --git a/reference/datetime/examples.xml b/reference/datetime/examples.xml index c58489eabed7..e8139edd67c5 100644 --- a/reference/datetime/examples.xml +++ b/reference/datetime/examples.xml @@ -10,14 +10,13 @@ The following examples show some pitfalls of Date/Time arithmetic with regard to DST transitions and months having different numbers of days. - - - DateTimeImmutable::add/sub add intervals which cover elapsed time - - Adding PT24H over a DST transition will appear to add 23/25 hours (for - most timezones). - - + + DateTimeImmutable::add/sub add intervals which cover elapsed time + + Adding PT24H over a DST transition will appear to add 23/25 hours (for + most timezones). + + 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; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - DateTimeImmutable::modify and strtotime increment or decrement individual component values - - 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). - - + + + + DateTimeImmutable::modify and strtotime increment or decrement individual component values + + 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). + + 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; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - Adding or subtracting times can over- or underflow dates - - Like where January 31st + 1 month will result in March 2nd (leap year) or - 3rd (normal year). - - + + + + DateInterval::createFromDateString creates intervals which increment or decrement component values + + DateInterval::createFromDateString 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 DateInterval::__construct 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 P1D and + 1 day always give the same result. + + +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; +]]> + + &example.outputs; + + + + + + Adding or subtracting times can over- or underflow dates + + Like where January 31st + 1 month will result in March 2nd (leap year) or + 3rd (normal year). + + 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; ]]> - - &example.outputs; - + + &example.outputs; + - - - To get the last day of the next month (i.e. to prevent the overflow), - the last day of format is available. - - + + + To get the last day of the next month (i.e. to prevent the overflow), + the last day of format is available. + + 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; ]]> - - &example.outputs; - + + &example.outputs; + - - - + +