CHAPTER 9 – DATE HANDLING – Retrieving Date and Time Information

The easiest way of obtaining the current time is with the time() function. It accepts no parameters and simply returns the current timestamp:

<?php 
echo time(); // Outputs something similar to "1077913162" 
?>

The resolution is 1 second. If you want some more accuracy, you have two options: microtime() and gettimeofday(). The microtime() function has one annoying peculiarity: The return value is a floating-point number containing the decimal part of the timestamp and the number of seconds since the epoch, concatenated with a space. This makes it, of course, a bit hard to use for a timestamp with sub-second resolution:

<?php
// Outputs something similar to "0.87395100 1078006447"
echo microtime();
$time = preg_replace('@^(.*)s+(.*)$@e', '\2 + \1',
microtime());
echo $time; // Outputs 1078006447.8741
?>

In putting the two parts back together, you lose some of the precision. The gettimeofday() function has a nicer interface. It returns an array with ele- ments representing the timestamp and additional microseconds. Two more elements are included in this array, but you cannot really rely on them because the underlying system functionality--at least in Linux--is not work- ing correctly:

<?php
print_r(gettimeofday());
?>
returns
Array
(
[sec] => 1078006910
[usec] => 339699
[minuteswest] => -60
[dsttime] => 0
)

localtime() and getdate() both return an array. The elements contain information belonging to the (optional) timestamp passed to the function. The returned arrays are not exactly the same. Table 9.5 shows what the elements in the arrays mean. Table 9.5 Elements in Arrays Returned by localtime() and getdate() Meaning Index (localtime()) Index (getdate()) Remarks Seconds tm_sec seconds Minutes tm_min minutes Table 9.5 Elements in Arrays Returned by localtime() and getdate() Meaning Index (localtime()) Index (getdate()) Remarks Hours tm_hour hours Day of month tm_mday mday Month tm_mon mon For localtime: Janu- ary=0; for getdate: January=1 Year tm_year year Day of week tm_wday wday With 0 being Sun- day and 6 being Saturday Day of year tm_yday yday With 0 being Janu- ary 1st and 366 being December 32nd DST in effect tm_isdst Set to true if Day- light Savings Time is in effect Textual day of weekday English name of the week weekday Textual month month English name of the month Timestamp Number of seconds 0 since 01-01-1970 The tm_isdst element of localtime() is especially interesting. It's the only way in PHP to see whether the server is in DST. Also, note that the month number in the return array of localtime() starts with 0, not with 1, which makes December month 11. The first parameter for both functions is a time stamp, allowing the functions to return date information based on the time you pass them, rather than just on the current time. localtime() normally returns an array with numerical indices, rather than the indices as described in the previous table. To signal the function to return an associative array, you need to pass true as the second parameter. If you want to return this associa- tive array with information about the current time, you need to pass the time() function as first parameter: <?php print_r(localtime(time(), true)); ?> Two more date functions are available: gmmktime() and mktime(). Both functions create a timestamp based on parameters passed when the function is called. The difference between the two functions is that gmmktime() treats the date/time parameters passed as a Greenwich Mean Time (GMT), while param- eters passed to mktime() are treated as local time. The order of parameters is not very user friendly, as you can see in the prototype of the following function: timestamp mktime ( [$hour [, $minute [, $second [, $month [, $day [, $year [, $is_dst]]]]]]]) Note the particularly weird order of the parameters. All parameters are optional. If any parameter is not included, the "current" value is used, depend- ing on the current date and time. The last parameter, is_dst, controls whether the date and time parameters that are passed to the function are DST-enabled or not. The default value for the parameter is -1, which signals PHP to deter- mine for itself whether the date falls into the range when DST is observed. Here is an example:

<?php
/* mktime with a date outside the DST range */
echo date("Ymd H:i:s", mktime(15, 16, 17, 1, 17, 2004)). "n";
echo date("Ymd H:i:s", mktime(15, 16, 17, 1, 17, 2004, 0)). "n";
echo date("Ymd H:i:s", mktime(15, 16, 17, 1, 17, 2004, 1)). "n";

/* mktime with a date inside the DST range */
echo date("Ymd H:i:s", mktime(15, 16, 17, 6, 17, 2004)). "n";
echo date("Ymd H:i:s", mktime(15, 16, 17, 6, 17, 2004, 0)). "n";
echo date("Ymd H:i:s", mktime(15, 16, 17, 6, 17, 2004, 1)).
"nn";
?>

The first three calls "make" a timestamp for January 17, in which no DST is observed. Therefore, setting the $is_dst parameter to 0 has no effect on the returned timestamp. If it's set to 1, though, the timestamp will be one hour earlier, as the mktime() function converts the DST time (which is always one hour ahead of non-DST). For the second set of mktime() calls, we use June 17 in which DST is observed. Setting the $is_dst parameter to 0 now makes the function convert the time from non-DST to DST and, thus, the returned time- stamp will be one hour ahead of the result of the first and third calls. The out- put is 20040217 15:16:17 20040217 15:16:17 20040217 14:16:17

20040617 15:16:17 20040617 16:16:17 20040617 15:16:17 It's best not to touch the $is_dst parameter, because PHP usually inter- prets the date and time correctly. If we replace all calls to mktime() by gmmktime(), the parameters passed to the function are treated as GMT time, with no time zones taken into account. With mktime(), the time zone that the server has configured is taken into account. For instance, if you are on Central European Time (CET), passing the same parameters as shown previously to gmmktime output times that are one hour "later." Because the date function does take into account time zones, the generated GMT timestamp is treated as a CET time zone, resulting in times that are one hour for non-DST times and two hours for DST times (CEST is CET+1).