Introduction

Since I wrote the original article about Handling Date and Time in PHP and MySQL several years ago, it seemed like now was a good time to update it for object-oriented PHP.  This article does that, replacing as much as possible the principles and examples of the original article on a 1:1 basis.  As I created the examples for this article, I came across some anomalies in the PHP OOP DateTime implementation.  Here are some of my impressions and some notable gotcha's that I found.

It is possible to create an infinite loop with date/time arithmetic.  Your code will look right, but transitions at the boundaries of daylight savings time will change the values in your DateTime objects.  I hope PHP will fix this.

See: http://php.net/manual/en/datetime.sub.php#114780

When you create a new DateTime object, you can assign both a date/time string and a timezone.  If you create the DateTime object from a Unix timestamp, the timezone cannot be used in the constructor.  You must assign the timezone to the object separately, after the object is created.

The ISO-8601 format for DateTime::format() method is not 100% ISO-8601 compatible.  You can use DateTime::ATOM instead if you need perfect compatibility.

The designator for a Unix timestamp in DateTime::__construct() is the at-sign ("@") prepended to the numeric Unix timestamp.  The at-sign ("@") is also the PHP error-control operator, but it has no error-control meaning in the DateTime constructor.

There is no avoiding arithmetic - DateTime::getOffset() returns its answer in seconds, but functions that use this information may expect minutes or hours.

I found no convenient way to instantiate a DateTime object and get a formatted date/time string in a single line of code.  The marriage of PHP date() and strtotime() was a convenience that is not here any more.  I'll update this article if I find a good solution.

At PHP 7.1+ the DateTime constructor incorporates microseconds when the object is constructed from the current time.  This may increase the risk that two DateTime objects will be unequal.

Now the good news.  Most of what you learned about date formatting with the date() format parameters is still applicable.  You will write a little more code with the OOP notation, but that is common for OOP programming and may help to improve readability.  And none of the common tasks we use in procedural PHP is impeded by the OOP DateTime notation.  A list of the most useful references is included at the end of this Article.

The DATE/TIME Tower of Babel

Human beings can read dates and times in a variety of ways.  We readily understand such things as September 5th, 2010, and we know that it comes before November 11th, 2010,and after May 9th, 2010.  We have shorthand conventions that let us write things like 9/5/2010 or the military correspondence format 5 Sep 2010.  But when we try to process dates and times in a computer program, this variety of formats becomes a jumble of confusion.  In response to the confusion, the International Organization for Standards was moved to publish a standard in 1988.  The standard has been revised and extended somewhat since the original publication.  The only thing that mystifies students of history is why it took so long to promulgate a standard.

Toward a Universal DATETIME Notation

Date formats for computer processing are prescribed by the ISO-8601 standard.  The ISO-8601 standard places all the information in fixed-width data strings with leading zeros where needed.  When you read ISO-8601 standard information you notice immediately that everything lines up in columns.  The larger values are to the left and progressively smaller values are to the right, starting with Year, then Month, then Day, then Hour, etc.  Date/time information formatted according to the standard is very useful because it is both easy to read and easy to understand in comparisons and computations.  For example, the date '2010-09-05' is a valid ISO-8601 string meaning September 5th, 2010.  Imagine how difficult it would be to write programming that works with dates in the text formats, or dates that are formatted like this: 05.09.2010.  Does that mean May 9th, 2010 or September 5th, 2010?  Fortunately the ISO-8601 standard removes the ambiguity.

The ISO-8601 standard removes the ambiguity about the time of day, as well.  All of the hours are represented on a 24-hour clock, so there is no question about what "two o'clock" might mean.  The string 0200 or 02:00:00 refers to 2:00 a.m.  If you're thinking of 2:00 p.m. your ISO-8601 standard will use 14:00:00.

This link gives a good discussion and examples of permissible variations on the ISO-8601 format.

See http://en.wikipedia.org/wiki/ISO_8601

The Value of PHP time() is Always the Same

No matter where in the world you stand, the value of time() is always the same.  The PHP function time() returns the number of seconds since the Unix Epoch.  While local times may differ, time() ticks on second-by-second.  Run this script to see the effect.  Knowing this, we can do arithmetic with seconds, and then return human-readable date and time values that are sensible for different locations around the world.

<?php
                                        /**
                                         * Different Timezones share the same Unix Timestamp
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        // TIMEZONES AROUND THE GLOBE
                                        $locations
                                        = array
                                        ( 'Pacific/Auckland'
                                        , 'Australia/Sydney'
                                        , 'Australia/Perth'
                                        , 'Asia/Tokyo'
                                        , 'Asia/Calcutta'
                                        , 'Asia/Tel_Aviv'
                                        , 'Africa/Cairo'
                                        , 'Europe/Rome'
                                        , 'Europe/London'
                                        , 'Atlantic/Bermuda'
                                        , 'America/Chicago'
                                        , 'America/Anchorage'
                                        , 'Pacific/Honolulu'
                                        , 'UTC'
                                        )
                                        ;
                                        // ITERATE OVER THE TIMEZONES
                                        foreach ($locations as $location)
                                        {
                                            // SET OUR ZONE AND LOCAL TIME
                                            $zoneobj = new DateTimeZone($location);
                                            $dateobj = new DateTime(NULL, $zoneobj);
                                        
                                            // SHOW THE LOCATION AND THE CURRENT DATE / TIME
                                            echo PHP_EOL;
                                            echo str_pad($location, 24, ' ');
                                            echo $dateobj->format(DateTime::RSS);
                                        
                                            // SHOW THE NUMBER OF SECONDS SINCE THE EPOCH, RECOMPUTED IN EACH TIMEZONE
                                            echo ' ';
                                            echo $dateobj->format('U');
                                        }

Handling External Input

Whenever you accept a date/time string from an external data source, what is the first thing you should do?  Turn it (immediately) into an instance of the DateTime object.  The DateTime constructor can turn almost any English language human-readable date/time text into an object for use in DateTime computations and displays. Like the PHP function date(), the DateTime::format() method can turn DateTime information into a formatted date. 

<?php 
                                        /**
                                         * The DateTime constructor may throw an Exception
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        $external = 'Yesterday';
                                        try
                                        {
                                            $dateobj = new DateTime($external);
                                        }
                                        catch (Exception $e)
                                        {
                                            // ON FAILURE, SHOW THE EXCEPTION
                                            var_dump($e);
                                        }
                                        echo PHP_EOL . $dateobj->format(Datetime::ATOM);
                                        echo PHP_EOL;

Once you have done that internal date format conversion your programming will handle internal date/time computations easily.

When you are storing date/time values, you may want to store them in the ISO-8601 format strings or in the form of Unix timestamps.  I prefer to use the formatted strings - they are easier to understand when you're debugging.

Handling External Input that is Invalid

The PHP DateTime constructor can turn virtually any human-readable date / time text into a DateTime object - but it won't work on everything.  When it fails to make the conversion, it throws Exception.  You can and should test for this.

<?php
                                        /**
                                         * Invalid date/time strings can be detected when you catch the Exception
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        $external = 'Nonsense';
                                        $dateobj  = FALSE;
                                        try
                                        {
                                            $dateobj = new DateTime($external);
                                        }
                                        catch (Exception $e)
                                        {
                                            // ON FAILURE, SHOW THE EXCEPTION
                                            var_dump($e);
                                        }
                                        if ($dateobj)
                                        {
                                            $iso_datetime = $dateobj->format(Datetime::ATOM);
                                            echo "SUCCESS: $external EQUALS ISO-8601 $iso_datetime";
                                        }
                                        else
                                        {
                                            echo "ERROR: I DO NOT UNDERSTAND $external";
                                        }

Handling External Input that is Formatted (contrary to the disambiguation rules)

The PHP DateTime Constructor works much the same way as strtotime(), making some assumptions and obeying certain rules about the format of the date / time input string.  But what if you have dates that are not formatted according to the rules?  One of the common issues arises when we have dates that are in European order d-m-y, but have been written with slashes, implying American order m/d/y.  This may result in incorrect output when the values for m and d  are both in the range from 1 - 12, and will cause an exception when m exceeds 12.  Fortunately PHP has a way around this issue, in the static constructor createFromFormat().  We can tell PHP what format to use as it interprets the date.  This example shows how.

<?php
                                        /**
                                         * Date values separated by slash are assumed to be in American order: m/d/y
                                         * Date values separated by dash are assumed to be in European order: d-m-y
                                         * Exact formats for date/time strings can be injected with createFromFormat()
                                         *
                                         * http://php.net/manual/en/datetime.createfromformat.php
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        // THIS WOULD IMPLY MONTH == 19, OBVIOUSLY INVALID
                                        $external = "19/10/2016 14:48:21";
                                        
                                        // HOWEVER WE CAN INJECT THE FORMATTING WHEN WE DECODE THE DATE
                                        $format = "d/m/Y H:i:s";
                                        $dateobj = DateTime::createFromFormat($format, $external);
                                        
                                        $iso_datetime = $dateobj->format(Datetime::ATOM);
                                        echo "SUCCESS: $external EQUALS ISO-8601 $iso_datetime";

Interesting Forms of External Input

All of these external inputs work correctly with the DateTime constructor and this gives you and your clients powerful ways of talking about dates and computing with dates.

- 3 hours

tomorrow

tomorrow midnight

tomorrow 1:35pm

March 15, 1986

yesterday

yesterday + 1 week

next year

now

now + 627 hours 15 minutes

last Tuesday

third Wednesday

3 minutes, 15 seconds

Producing "Pretty" Dates From DateTime Objects ISO-8601 Dates

When you are ready to present the dates to people and you want them to see nicely formatted dates, you can use the DateTime::format() method to do the reformatting.  Let's say you have this timestamp value: 1,284,593,400 (which equals the ISO-8601 date: '2010-09-15T18:30:00-0500'. )  Maybe you got it out of your data base or computed it in your script.  It's meaningful, but not what you expect when you open the envelope.  "Please join us for cocktails on Unix Timestamp 1,284,593,400."  How can we get something that would be appropriate on an invitation?  Here is how you might do the conversion from a timestamp or ISO-8601 date to the pretty date.

<?php 
                                        /**
                                         * The DateTime::format() can change the rendering of date values and produce pretty dates
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        $iso_date = '2010-09-15T18:30:00';
                                        $formats  = 'l, F jS, Y \a\t g:ia';
                                        $dateobj  = new DateTime($iso_date);
                                        echo PHP_EOL . $dateobj->format($formats);

Outputs "Wednesday, September 15th, 2010 at 6:30pm" -- very civilized!

Breaking down the date formatting, we have the following (all documented on PHP.net)...

$pattern
                                        = 'l, '    // LOWERCASE L - text name of the day of the week
                                        . 'F '     // UPPERCASE F - text name of the month
                                        . 'j'      // LOWERCASE J - day of the month
                                        . 'S, '    // UPPERCASE S - ordinal like the letters in 1st, 2nd, etc 
                                        . 'Y '     // UPPERCASE Y - 4-digit year
                                        . '\a\t '  // ESCAPED LETTERS... More to follow
                                        . 'g:'     // LOWERCASE G - hours on a 12-hour clock
                                        . 'i'      // LOWERCASE I - minutes 
                                        . 'a'      // LOWERCASE A - designator of "am" or "pm"
                                        ;

You might envision several patterns that you need in your application.  Most PHP sites and services are written with a central "common.php" file that gets included into all the specialized scripts.  You could prepare the formatting patterns in the common script and refer to them by a variable name, or define the patterns as constants.

define('MILITARY_CORRESPONDENCE', 'j M y');
                                        define('SHORT_8601', 'Y-m-d');
                                        define('COCKTAILS', 'l, F jS, Y \a\t g:ia');

What about the escaped letters?  Like the date() function, the DateTime::format() uses letter patterns as signals to describe the conversion into human-readable character strings, so some letters have special relevance and some do not.  Any character that is not used as a signal in the date pattern string is returned from the function unaltered.  Punctuation is one example - commas and hyphens go right through.  But if we want to get one of the signal letters back, we must tell PHP to ignore the signal and just return the letter.  We do that with the back-slash character, as shown here.  Try running these two lines of code to see how the escape can be useful:

echo PHP_EOL . date('The year is: Y');
                                        echo PHP_EOL . date('\T\h\e \y\e\a\r\ \i\s\: Y');

Setting Your Own Clock Values

Since the values contained in the DateTime object are usable in many different time zones, you want to have control over the way PHP interprets the time zone.  You control this time with the DateTimeZone object.  You can set the DateTimeZone in the DateTime constructor, or you can inject a new DateTimeZone into a DateTime object via the setTimeZone() method.  Here is an example that I use, because my server is located in the midwest at ChiHost.com.

<?php
                                        /**
                                         * DateTime objects are usually aware of time zones via the DateTimeZone object
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        $string  = 'Now';
                                        $zoneobj = new DateTimeZone("America/Chicago");
                                        $formats = 'l, F jS, Y \a\t g:ia (e)';
                                        $dateobj = new DateTime($string, $zoneobj);
                                        echo PHP_EOL . $dateobj->format($formats);
                                        
                                        // WHAT TIMEZONE SHOULD I USE?
                                        $tz_ids = DateTimeZone::listIdentifiers(DateTimeZone::PER_COUNTRY, 'US');
                                        foreach($tz_ids as $zone)
                                        {
                                            echo PHP_EOL . $zone;
                                        }

Special Meanings for NOW and TODAY

We know how to convert external date/time strings into DateTime objects, and we know how to return them to human-preferred formats with DateTime::format().  Now we can return to some of the special meanings of date/time strings.  NOW and TODAY are particularly useful.

<?php 
                                        /**
                                         * NOW and TODAY have special meanings in the DateTime object; NOW includes time of day
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        $date = new DateTime('Now');
                                        echo PHP_EOL . $date->format(DateTime::RSS);
                                        
                                        $date = new DateTime('Today');
                                        echo PHP_EOL . $date->format(DateTime::RSS);
                                        
                                        $date = new DateTime('Now', new DateTimeZone('UTC'));
                                        echo PHP_EOL . $date->format(DateTime::RSS);
                                        
                                        $date = new DateTime('Today', new DateTimeZone('UTC'));
                                        echo PHP_EOL . $date->format(DateTime::RSS);

The principal difference between NOW and TODAY is the time of day.  TODAY is always today's local date at midnight, with hour, minute and second equal to zero.  NOW is today's date including the current time of day.  So in our September example, NOW and TODAY have UNIX timestamp values equal to 1,284,593,400 and 1,284,526,800 respectively.  The difference is 66,600.  This is the number of seconds from midnight to 6:30pm (18 hours plus 30 minutes).  

This script shows that the Unix timestamp is consistent, no matter what timezone you have specified.

<?php 
                                        /**
                                         * The Unix Timestamp values for NOW and TODAY are the same, no matter what timezone
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        $dateobj = new DateTime('Now');
                                        echo PHP_EOL . $dateobj->format('U');
                                        
                                        $dateobj = new DateTime('Today');
                                        echo PHP_EOL . $dateobj->format('U');
                                        
                                        $dateobj = new DateTime('Now', new DateTimeZone('UTC'));
                                        echo PHP_EOL . $dateobj->format('U');
                                        
                                        $dateobj = new DateTime('Today', new DateTimeZone('UTC'));
                                        echo PHP_EOL . $dateobj->format('U');

Computing the Difference Between DateTime Objects

This script shows how to compute the difference between two DateTime objects, using the diff() method.

<?php 
                                        /**
                                         * Computing the difference between NOW and TODAY in different timezones
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        // TESTING UTC
                                        $zoneobj    = new DateTimeZone('UTC');
                                        $date_now   = new DateTime('Now',   $zoneobj);
                                        $date_today = new DateTime('Today', $zoneobj);
                                        $date_diff  = $date_now->diff($date_today);
                                        $print_diff = $date_diff->format('%H:%i:%S');
                                        
                                        echo PHP_EOL . $zoneobj->getName();
                                        echo PHP_EOL . $print_diff;
                                        echo PHP_EOL;
                                        
                                        // TESTING ANOTHER ZONE
                                        $zoneobj    = new DateTimeZone('America/New_York');
                                        $date_now   = new DateTime('Now',   $zoneobj);
                                        $date_today = new DateTime('Today', $zoneobj);
                                        $date_diff  = $date_now->diff($date_today);
                                        $print_diff = $date_diff->format('%H:%i:%S');
                                        
                                        echo PHP_EOL . $zoneobj->getName();
                                        echo PHP_EOL . $print_diff;
                                        echo PHP_EOL;
                                        
                                        // USING METHOD CHAINING FOR TIGHTER CODE
                                        $print_diff  = $date_now->diff($date_today)->format('%H:%i:%S');
                                        
                                        echo PHP_EOL . $zoneobj->getName();
                                        echo PHP_EOL . $print_diff;
                                        echo PHP_EOL;

As you can see, it is important to be consistent about your timezone.  You can deal with this phenomenon in one of two ways.  You can set your timezone to UTC.  Or you can set your timezone to a reasonable setting for the location of your server.  I prefer the latter.  See http://php.net/manual/en/timezones.php and http://php.net/manual/en/timezones.others.php for more.

Time Without Date

Let's say we want to know the elapsed time between two events, and we want to express it in notation like HH:MM:SS. DateTime::diff() and DateTime::format() can help with this.

<?php 
                                        /**
                                         * Computing the difference between two times
                                         */
                                        error_reporting(E_ALL);
                                        echo '<pre>';
                                        
                                        $alpha = "2:30:47pm";
                                        $omega = "3:43:16pm";
                                        $date_alpha = new DateTime($alpha);
                                        $date_omega = new DateTime($omega);
                                        $elapsed    = $date_omega->format('U') - $date_alpha->format('U');
                                        $date_diff  = $date_omega->diff($date_alpha);;
                                        $print_diff = $date_diff->format('%H:%i:%S');
                                        
                                        echo PHP_EOL . "TWIXT $alpha AND $omega THERE ARE " . number_format($elapsed) . " SECONDS";
                                        echo PHP_EOL . "RIGHT ELAPSED TIME IS $print_diff";

Leap Year and Daylight Savings Time

These are amazingly easy in PHP.  But beware of a bug in DateTime::add(), illustrated in this code.