Request for Comments: DateTime and Daylight Saving Time Transitions

• Version: 1.0
• Date: 2011-10-18
• Author: Daniel Convissor danielc@php.net with feedback from Derick Rethans derick@php.net
• Status: Approved (voting results)
• First Published at: https://wiki.php.net/rfc/datetime_and_daylight_saving_time

PHP's DateTime class has unexpected outcomes when dealing with the transitions between Daylight Saving Time and Standard Time.

Properly defining, documenting and unit testing DateTime's behaviors is important for PHP's future. This document seeks agreement on what the expected behaviors should be.

Getting these issues straightened out before 5.4 goes into Release Candidate status seems wise.

PHP uses three different time zone data structures internally.

Zone Type 3 objects contain the transition data required for proper calculations around the Daylight/Standard time changes.

Zone Type 1 and 2 objects just know their offset from UTC, so addition and subtraction on them ignore crossing over Daylight/Standard thresholds.

This RFC focuses on the changes needed to make Zone Type 3 work in a comprehensive manner. Zone Type 1 and 2 behaviors are covered to clarify their expected behavior.

Examples of how to create DateTime objects containing each zone type:

$d = new DateTime('2011-09-13 14:15:16 -0400');

$d = new DateTime('2011-09-13 14:15:16 EDT');

$d = new DateTime('2011-09-13 14:15:16');
// or
$d = new DateTime('2011-09-13 14:15:16', new DateTimeZone('America/New_York'));

The America/New_York time zone will be used for demonstration purposes. The Standard/Daylight transition in this zone happens at 2:00 am. The forward transition (in spring) jumps to 3:00 am, skipping over the hour of 2 am. The backward transition (in fall) jumps back to 1:00 am, repeating the hour of 1 am.

Other time zone changes have different lengths of time and take effect at different days/times.

Times between 2:00:00 am and 2:59:59 am do not exist during the Forward Transitions transition. Attempts to create such times should be rounded forward, like PHP currently does when trying to create February 29th on a non-leap year.

date_default_timezone_set('America/New_York');
$date = new DateTime('2010-03-14 02:30:00');
echo $date->format('Y-m-d H:i:s T') . "\n";
// Expected: 2010-03-14 03:30:00 EDT
// Actual:   2010-03-14 02:30:00 EDT

PHP needs a means to create objects representing times during the hour repeated on the Daylight/Standard transition day (between 1:00:00 am and 1:59:59 am Standard Time).

This RFC proposes adjusting the time string parser to handle strings containing DST and ST. When DST or ST are not present, PHP will use the current behavior, which uses the time zone offset in place at the specified time and uses DST offset during the repeated hour during backward transitions.

Force Daylight Saving Time:

date_default_timezone_set('America/New_York');
$date = new DateTime('2010-11-07 01:30:00 DST');
echo $date->format('Y-m-d H:i:s T') . "\n";
// Expected: 2010-11-07 01:30:00 EDT

Force Standard Time:

date_default_timezone_set('America/New_York');
$date = new DateTime('2010-11-07 01:30:00 ST');
echo $date->format('Y-m-d H:i:s T') . "\n";
// Expected: 2010-11-07 01:30:00 EST

Default to Daylight Time during repeated hour, PHP's current behavior:

date_default_timezone_set('America/New_York');
$date = new DateTime('2010-11-07 01:30:00');
echo $date->format('Y-m-d H:i:s T') . "\n";
// Expected & Actual: 2010-11-07 01:30:00 EDT

The ST or DST modifiers can only be used when specifying times during the backward transition period. Using the modifiers at other times will throw an exception in object-oriented style code while procedural style code will return false without triggering errors.

The date format used in this section is for display purposes only, does not correspond to a PHP format, nor is intended to be parsed by PHP.

Reminder: the time zone in the examples is America/New_York. So “(ST)” represents Eastern Standard Time/EST/-0500 and “(DT)” represents Eastern Daylight Time/EDT/-0400.

The behaviors indicated here are covered by unit tests in ext/date/tests:

• rfc-datetime_and_daylight_saving_time-type1.phpt
• rfc-datetime_and_daylight_saving_time-type2.phpt
• rfc-datetime_and_daylight_saving_time-type3.phpt

Each output line in the test files is prefixed with an identifier that corresponds to the phpt columns in the tables below.

Actual results for Zone Types 1 and 2 are shown as N/A for the moment. All Zone Type 1 tests pass. Zone Type 2 results are tainted by Bug 55253.

If you know of other problems, please bring them to the attention of the authors.