Chapter 7. Dates and Times

The typical PHP developer likely needs to be aware of the available date and time functions, such as when adding a date stamp to a database record entry or calculating the difference between two dates. PHP provides a DateTime class that can handle both date and time information simultaneously, as well as a DateTimeZone class that works hand in hand with it.

Time zone management has become more prominent in recent years with the onset of web portals and social web communities like Facebook and Twitter. To be able to post information to a website and have it recognize where you are in the world in relation to others on the same site is definitely a requirement these days. However, keep in mind that a function like date() takes the default information from the server on which the script is running, so unless the human clients tell you where they are in the world, it can be quite difficult to determine time zone location automatically. Once you know the information, though, it’s easy to manipulate that data (more on time zones later in this chapter).

There are four interrelated classes for handling dates and times. The DateTime class handles dates themselves; the DateTimeZone class handles time zones; the DateInterval class handles spans of time between two DateTime instances; and finally, the DatePeriod class handles traversal over regular intervals of dates and times. There are two other rarely used supporting classes called DateTimeImmutable and DateTimeInterface that are part of the whole DateTime “family,” but we won’t cover those in this chapter.

The constructor of the DateTime class is naturally where it all starts. This method takes two parameters, the timestamp and the time zone. For example:

$dt = new DateTime("2019-06-27 16:42:33", new DateTimeZone("America/Halifax"));

We create the $dt object, assign it a date and time string with the first parameter, and set the time zone with the second parameter. Here, we’re instantiating the DateTimeZone instance inline, but you could alternately instantiate the DateTimeZone object into its own variable and then use that in the constructor, like so:

$dtz = new DateTimeZone("America/Halifax");
$dt = new DateTime("2019-06-27 16:42:33", $dtz);

Now obviously we are assigning hardcoded values to these classes, and this type of information may not always be available to your code or it may not be what you want. Alternatively, we can pick up the value of the time zone from the server and use that inside the DateTimeZone class. To pick up the current server value, use code similar to the following:

$tz = ini_get('date.timezone');
$dtz = new DateTimeZone($tz);
$dt = new DateTime("2019-06-27 16:42:33", $dtz);

These code examples establish a set of values for two classes, DateTime and DateTimeZone. Eventually, you will be using that information in some way elsewhere in your script. One of the methods of the DateTime class is called format(), and it uses the same formatting output codes as the date_format() function does. Those date format codes are all listed in the appendix, in the section for the date_format() function. Here is a sample of the format() method being sent to the browser as output:

echo "date: " . $dt->format("Y-m-d h:i:s");
date: 2019-06-27 04:42:33

So far we have provided the date and time to the constructor, but sometimes you will also want to pick up the date and time values from the server. To do that, simply provide the string "now" as the first parameter.

The following code does the same as the other examples, except here we are getting the date and time class values from the server. In fact, since we are getting the information from the server, the class properties are much more fully populated (note that some instances of PHP will not have this parameter set and thus will return an error, and the server’s time zone may not match your own):

$tz = ini_get('date.timezone');
$dtz = new DateTimeZone($tz);
$dt = new DateTime("now", $dtz);

echo "date: " . $dt->format("Y-m-d h:i:s");
date: 2019-06-27 04:02:54

The diff() method of DateTime does what you might expect—it returns the difference between two dates. The return value of the method is an instance of the DateInterval class.

To get the difference between two DateTime instances, use:

$tz = ini_get('date.timezone');
$dtz = new DateTimeZone($tz);

$past = new DateTime("2019-02-12 16:42:33", $dtz);
$current = new DateTime("now", $dtz);

// creates a new instance of DateInterval
$diff = $past->diff($current);

$pastString = $past->format("Y-m-d");
$currentString = $current->format("Y-m-d");
$diffString = $diff->format("%yy %mm, %dd");

echo "Difference between {$pastString} and {$currentString} is {$diffString}";
Difference between 2019-02-12 and 2019-06-27 is 0y 4m, 14d

The diff() method is called on one of the DateTime objects with the other DateTime object passed in as a parameter. Then we prepare the browser output with the format() method calls.

Notice that the DateInterval class has a format() method as well. Since it deals with the difference between two dates, the format character codes are slightly different from that of the DateTime class. Precede each character code with a percent sign, %. The available character codes are provided in Table 7-1.

Let’s look a little more closely at the DateTimeZone class now. The time zone setting can be lifted out of the php.ini file with get_ini(). You can get more information from the time zone object using the getLocation() method. It provides the country of origin of the time zone, the longitude and the latitude, plus some comments. With these few lines of code, you can have the beginnings of a web-based GPS system:

$tz = ini_get('date.timezone');
$dtz = new DateTimeZone($tz);

echo "Server's Time Zone: {$tz}<br/>";

foreach ($dtz->getLocation() as $key => $value) {
 echo "{$key} {$value}<br/>";
}
Server's Time Zone: America/Halifax
country_code CA
latitude 44.65
longitude -63.6
comments Atlantic - NS (most areas); PE

If you want to set a time zone other than the server’s, you must pass that value to the constructor of the DateTimeZone object. This example sets the time zone for Rome, Italy, and displays the information with the getLocation() method:

$dtz = new DateTimeZone("Europe/Rome");

echo "Time Zone: " . $dtz->getName() . "<br/>";

foreach ($dtz->getLocation() as $key => $value) {
 echo "{$key} {$value}<br/>";
}

Time Zone: Europe/Rome
country_code IT
latitude 41.9
longitude 12.48333
comments

A list of valid time zone names by global regions can be found in the PHP online manual (https://www.php.net/manual/en/timezones.php).

Using this same technique, you can make a website “local” to a visitor by providing a list of supported time zones for the visitor to choose from and then temporarily adjusting your php.ini setting with the ini_set() function for the duration of the visit.

While there’s a fair amount of date and time processing power provided by the classes that we discussed in this chapter, it’s only the proverbial tip of the iceberg. Be sure to read more about these classes and what they can do on the PHP website.