Using PHP like a Pro #1 - Handling Dates, Times, and Timestamps - Part 1

Almost every web application requires parsing dates, times, and timestamps at some point. I have seen many overcomplicated approaches to this subject and I want to show you how to handle the time like a pro.

Note: For this tutorial, I presume that you use a PHP version >= 5.3.0. Make sure, you actually try out the code examples, so you can see all the output.

1. Timestamps

A timestamp contains the number of seconds since 00:00:00 UTC on January 1st, 1970. UTC stands for "Coordinated Universal Time". The different timezones that are being used in the world can all be represented by an offset to UTC.
It is always a good idea to store dates and times as timestamps. They can be converted to the local time of any timezone. Moreover, comparing them is as simple as comparing numbers. Tasks like finding the biggest timestamp (refering to the latest point in time) can be easily realized.

2. The DateTime class

PHP provides a class called DateTime, which offers a variety of methods to handle dates, times, and timestamps. Some methods of the DateTime class rely on instances of other classes like DateInterval, and DateTimezone.

In this tutorial I will explain the basics of the DateTime class. In the next tutorials, I will go into more detail.

3. Displaying the current server time

In the first example, I will show you how to retrieve the current time of your webserver and other time-specific information.

Code example 1:

<?php

$now = new DateTime();

//output the local time of the web server
echo "Current time: " . $now->format('m/d/Y h:i a') . "<br><br>";

//output the corresponding timestamp
echo "Current timestamp: " . $now->getTimestamp() . "<br><br>";

//output the current timezone of the web server
echo "Current timezone: " . $now->getTimezone()->getName() . "<br><br>";

//output the current UTC offset of the web server
echo "UTC offset in seconds: " . $now->getOffset();

?>

Note: If you create a DateTime object without any arguments, it will automatically use the local time and timezone of your server.
The format-method requires a format string as an argument. This will be explained in more detail in code example 3.

4. Converting timestamps to human-readable formats

In the second example, I will show you how to output the timestamps in a human-readable format.

Code example 2:

<?php

//create an instance of the DateTime-class
$datetime = new DateTime();

//create an array containing some example timestamps
$timestamps = array(0,1000000000,2000000000);

for ($i = 0; $i < count($timestamps); $i++) {

    //set the timestamp
    $datetime->setTimestamp($timestamps[$i]);
    
    //set the timezone to UTC +01:00 (Europe/Paris)
    $datetime->setTimezone(new DateTimeZone('Europe/Paris'));

    //output the time in a human-readable format
    echo "The timestamp value " . $timestamps[$i] . " is equivalent to the following local time in Paris: " . $datetime->format('m/d/Y h:i a') . "<br>";
    
    //set the timezone to UTC +9:00 (Asia/Tokyo)
    $datetime->setTimezone(new DateTimeZone('Asia/Tokyo'));

    //output the time in a human-readable format
    echo "The timestamp value " . $timestamps[$i] . " is equivalent to the following local time in Tokyo: " . $datetime->format('m/d/Y h:i a') . "<br>";
        
    //set the timezone to UTC -10:00 (Pacific/Honolulu)
    $datetime->setTimezone(new DateTimeZone('Pacific/Honolulu'));

    //output the time in a human-readable format
    echo "The timestamp value " . $timestamps[$i] . " is equivalent to the following local time in Honolulu: " . $datetime->format('m/d/Y h:i a') . "<br><br>"; 
}

?>

Note: As you can see, the timestamps can be converted into any local time by using the setTimezone-method. You can find a list of the supported timezones here.

5. Using the format function

In the first two examples the human-readable ouput was in a typical English (US) format. Of course, you can use other formats. You only need to change the format string according to your needs.

Code example 3:

<?php

$now = new DateTime();

echo "Current date in English (US) format: " . $now->format('m/d/Y') . "<br><br>";

echo "Current date in another English (US) format: " . $now->format('F jS') . "<br><br>";

echo "Current time (including the seconds) in 12-hour format: " . $now->format('h:i:s a') . "<br><br>";

echo "Current time (including the seconds) in 24-hour format: " . $now->format('H:i:s') . "<br><br>";

echo "Current time (including the seconds) in 24-hour format, followed by the timezone identifier: " . $now->format('H:i:s O') . "<br><br>";

echo "Current date in German format: " . $now->format('d.m.Y') . "<br><br>";

echo "Current date in Chinese format: " . $now->format('Y-m-d');

?>

Note: The format method evaluates reserved characters within the format string and replaces them with specific values. You are free to create every output format you like. The format-method uses the same reserved characters as PHP's (old) date-function. You can find all reserved characters here.

If you don't want a reserved character to be replaced, then you have to escape it with a backslash. The following code example will demonstrate this.

Code example 4:

<?php

$now = new DateTime();

//escape reserved characters with a backslash
echo $now->format('\T\o\d\a\y \i\s \t\h\e jS \d\a\y \of \t\h\e \m\o\n\t\h.');

?>

6. Parsing dates from strings

The following code example is a short preview of the next tutorial and shows how to parse a common date string. For example, a user interface might require the user to enter a date in a specific format like "08-24-2017" (refering to August 24th in the year 2017).

Code example 5:

<?php

//simulate the user input
$user_input = "08-24-2017";

//use the static createFromFormat-method to create a DateTime-object
$datetime = DateTime::createFromFormat('m-d-Y', $user_input);

echo "The user's input in another format: " . $datetime->format('F jS Y') . "<br><br>";

echo "The user's input converted into a timestamp: " . $datetime->getTimestamp();

?>

Note: As you can see, this is somewhat similar to the format-method (Code example 3) as we need to define the expected format in a format string as well. However, these format strings differ quite a bit. You can take a look at the reference of the createFromFormat-method here.

The createFromFromat-method will be explained in detail in the next tutorial. Also, I will walk you through the comparison of dates and times, explain intervals and periods, and go through some common use cases.

Feel free to ask questions! I will try to answer them as good as possible. If you find any mistakes, please let me know! Also, you may request tutorials on other subjects.

If you enjoyed this tutorial and found it to be helpful, then please follow my blog. Of course, I would appreciate an upvote as well :)