3.4 Dates and Times

There are several PHP library functions that work with dates and times. Most either generate a Unix timestamp or format a Unix timestamp in a human-readable form. Validation using dates, and working with the flexible PEAR Date package, is discussed in Chapter 9. In this section, we introduce timestamps and PHP library functions that work with Dates and Times.

3.4.1 Generating a Timestamp

A Unix timestamp consists of the number of seconds since the arbitrarily chosen time 1 January 1970 00:00:00 Greenwich Mean Time. Most systems represent a timestamp using a signed 32-bit integer, allowing a range of dates from December 13, 1901 through January 19, 2038. While timestamps are convenient to work with, care must be taken when manipulating timestamps to avoid integer overflow errors. While PHP automatically converts integers that overflow to floats, these values aren't valid timestamps.

In the Microsoft Windows environment, the timestamp functions don't support negative timestamps and can be used only with dates between January 1, 1970 and January 19, 2038.


3.4.1.1 Current time

PHP provides several functions that generate a Unix timestamp. The simplest:

integer time( )

returns the timestamp for the current date and time, as shown in this fragment:

// prints the current timestamp: e.g., 1064699133

print time( );

3.4.1.2 Creating timestamps with mktime( ) and gmmktime( )

To create a timestamp for a past or future date in the range December 13, 1901 through January 19, 2038, the mktime( ) and gmmktime( ) functions are defined:

int mktime(int hour, int minute, int second, int month, int day, int year [, int is_dst])
int gmmktime(int hour, int minute, int second, int month, int day, int year [, int is_dst])

Both create a timestamp from the parameters supplied; the parameters supplied to gmmktime( ) represent a GMT date and time, while the parameters supplied to mktime( ) represent the local time. This example creates a timestamp for 9:30 A.M. on June 18, 1998:

$aDate = mktime(9, 30, 0, 6, 18, 1998);

Both functions correctly handle parameter values that you might consider out-of-range. For example, the following call passes 14 for the month value, 29 for the day, and 2004 for the year, creating a time stamp for 1 March 2005:

// Creates a time stamp for 1 March 2005

$aDate = mktime(0, 0, 0, 14, 29, 2004);

Setting the month to 14 and the year to 2004 overflows to February in 2005 and setting the day to 29 overflows to the first of March. This characteristic allows scripts to add a quantum of time without range checking. The following example shows how 30 days can be added to a date and time:

$paymentPeriod = 30;  // Days



// generates a timestamp for 26 June 2002 by

// adding 30 days to 27 May 2002

$paymentDue = mktime(0, 0, 0, 5, 27 + $paymentPeriod, 2002);



// A different approach adds the appropriate number 

// of seconds to the timestamp for 27 May 2002

$paymentDue = mktime(0, 0, 0, 5, 27, 2002) 

              + ($paymentPeriod * 24 * 3600);

If the components of a date are outside the range of dates the function is defined for, -1 is returned. Both functions allow the supplied date to be interpreted as daylight savings time by setting the flag is_dst to 1.

The order of the arguments to these functions is unusual and easily confused. While the mktime( ) and gmmktime( ) functions are similar to the Unix mktime( ) function, the arguments aren't in the same order.

3.4.1.3 String to timestamp

The strtotime( ) function generates a timestamp by parsing a human-readable date and time (between December 13, 1901 and January 19, 2038) from the string time:

integer strtotime(string time)

The function interprets several standard representations of a date, as shown here:

// Absolute dates and times

$var = strtotime("25 December 2002");

$var = strtotime("14/5/1955");

$var = strtotime("Fri, 7 Sep 2001 10:28:07 -1000");



// The current time: equivalent to time( )

$var = strtotime("now");



// Relative to now

print strtotime("+1 day"); // tomorrow

print strtotime("-2 weeks"); // two weeks ago

print strtotime("+2 hours 2 seconds"); // in two hours and two seconds

Care should be taken when using strtotime( ) with user-supplied dates. It's better to limit the use of strtotime( ) to cases when the string to be parsed is under the control of the script. For example, it's used here to check a minimum age using a relative date:

// date of birth: timestamp for 16 August, 1982

$dob = mktime(0, 0, 0, 8, 16, 1982);



// Now check that the individual is over 18

if ($dob < strtotime("-18 years"))

    print "Legal to drive in the state of Victoria"; // prints

3.4.1.4 Subsecond times

A Unix timestamp represents a date and time accurate to the second, but many applications require times to be represented to the subsecond. PHP provides the function:

string microtime( )

The microtime( ) function returns a string that contains both a Unix timestamp in seconds and a microsecond component. The returned string begins with the microsecond component, followed by the integer timestamp:

// prints the time now in the format "microsec sec"

// Example: 0.55512200 1064700291

print microtime( );

One common use of the function microtime( ) is to generate an integer seed for a random-number generator:

// Generate a seed.

$seed = (float)microtime( ) * 1000000;



// prints (for example) 555206

print $seed;

Because the microsecond component appears at the start of the string returned from microtime( ), the returned value can be converted to a float with the (float) cast operator. Multiplying the float result by 1,000,000 ensures that you create a suitably varying integer.

The following fragment shows how you can use both the microsecond and second components to create a floating point representation of the time:

$parts = explode(" ", microtime( ));

$f = (float)$parts[0] + (int)$parts[1];



// prints (for example) 1064700291.56 

print $f;

3.4.2 Formatting a Date

While the Unix timestamp is useful in a program, it isn't a convenient display format. The date( ) and gmdate( ) functions return a human-readable formatted date and time:

string date(string format [, integer timestamp])
string gmdate(string format [, integer timestamp])

The format of the returned string is determined by the format argument. Passing in the optional timestamp argument can format a predetermined date. Otherwise, both functions format the current time. The format string uses the formatting characters listed in Table 3-3 to display various components or characteristics of the timestamp. To include characters without having the function interpret them as formatting characters, escape them with a preceding backslash character. The following examples show various combinations:

// Set up a timestamp for 08:15am 24 Aug 1974

$var = mktime(8, 15, 25, 8, 24, 1974);



// "24/08/1974"

print date('d/m/Y', $var);



// "08/24/74"

print date('m/d/y', $var);



// prints "Born on Saturday 24th of August" 

print date('\B\o\r\n \o\n l jS \of F', $var);

Table 3-3. Formatting characters used by the date( ) function

Formatting character

Meaning

a, A

"am" or "pm"; "AM" or "PM"

S

Two-character English ordinal suffix: "st", "nd", "rd", "th"

d, j

Day of the month: with leading zeros e.g., "01"; without e.g., "1"

D, l

Day of the week: abbreviated e.g., "Mon"; in full e.g., "Monday"

M, F

Month: abbreviated e.g., "Jan"; in full e.g., "January"

m, n

Month as decimal: with leading zeros: "01"-"12"; without: "1"-"12"

h, g

Hour 12-hour format: with leading zeros e.g., "09"; without e.g., "9"

H, G

Hour 24-hour format: with leading zeros e.g., "01"; without e.g., "1"

I

Minutes:"00" to "59"

s

Seconds: "00" to "59"

Y, y

Year: with century e.g., "2004"; without century e.g., "04"

r

RFC-2822 formatted date: e.g., "Tue, 29 Jan 2002 09:15:33 +1000" (added in PHP 4.0.4)

w

Day of the week as number: "0" (Sunday) to "6" (Saturday)

t

Days in the month: "28" to "31"

z

Days in the year: "0" to "365"

B

Swatch Internet time

L

Leap year: "0" for normal year; "1" for leap year

I

Daylight savings time: "0" for standard time; "1" for daylight savings

O

Difference to Greenwich Mean Time in hours: "+0200"

T

Time zone setting of this machine

Z

Time zone offset in seconds: "-43200" to "43200"

U

Seconds since the epoch: 00:00:00 1/1/1970


PHP also provides the equivalent functions:

string strftime(string format [, integer timestamp])
string gmstrftime(string format [, integer timestamp])

The format string uses the same % sequence formatting character sequences as the C library function strftime( ). For example:

// Prints "24/08/1974 08:15:25"

print strftime("%d/%m/%Y %H:%M:%S", mktime(8, 15, 25, 8, 24, 1974));



// Prints "08/24/1974"

print strftime("%D", mktime(8, 15, 25, 8, 24, 1974));

The result of some % sequences used by strftime( ) and gmstrftime( ) depends on the locale settings. The following sets the locale so the printed date used the Estonian language and conventions:

setlocale (LC_TIME, 'es');



// prints "laupäev 24 august 1974"

print strftime ("%A %d %B %Y", mktime(8, 15, 25, 8, 24, 1974));

Formatting sequences supported by strftime( ) and gmstrftime( ) are shown in Table 3-4. Some of these % sequences are not supported under Windows as noted.

Table 3-4. Formatting characters used by the strftime( ) and gmstrftme( ) functions

Formatting sequence

Meaning

%a, %A

Day of the week dependant on locale settings: abbreviated e.g., "Mon"; in full e.g., "Monday".

%b, %B

Month: abbreviated e.g., "Jan"; in full e.g., "January"

%c, %x, %X

Default Date and Time format for the local settings: with time e.g., "01/27/04 22:06:03"; without time e.g., "01/27/04"; without the date e.g., "06:03"

%C

Century e.g., "04" for 2004 (does not work with Windows)

%d

Day of month padded with leading zero e.g., "01"

%D

Same as "%m/%d/%y" (does not work with Windows)

%e

Day of month padded with leading space e.g., "1" (does not work with Windows)

%H, %I

Hour: 24-hour format with leading zero e.g., "15"; 12-hour format with leading zero e.g., "03"

%j

Day of the year: "001" to "366"

%m

Month with leading zero e.g., "01"

%M

Minute with leading zero e.g., "01"

%p

"AM" or "PM". Value dependant on locale settings

%r

Time in am/pm notation (does not work with Windows)

%R

Time in 24 hour notation (does not work with Windows)

%S

Seconds with leading zero

%T

Same as "%H:%M:%S" (does not work with Windows)

%u, %w

Day of the week as a decimal: 1-7 with "1" = Monday, "2" = Tuesday, etc..; 0-6 with "0" = Sunday, "1" = Monday, etc.. %u (does not work with Windows)

%U

Week number in a year where the first week starts with the first Sunday in the year

%V

Week number in a year where the first week is the week, with at least four days, starting on a Monday, in the current year. This is the ISO 8601:1988 definition of the week number (does not work with Windows)

%W

Week number in a year where the first week starts with the first Monday in the year

%y, %Y

Year: without the century e.g., "04" for 2004; with the century e.g., "2004"

%Z

Time zone information e.g., "AUS Eastern Standard Time"

%%

Literal % character


3.4.3 Validating a Date

The function checkdate( ) returns true if a given month, day, and year form a valid Gregorian date:

boolean checkdate(integer month, integer day, integer year)

This function isn't based on a timestamp and so can accept any dates in the years 1 to 32767. It automatically accounts for leap years.

// Works for a wide range of dates

$valid = checkdate(1, 1, 1066); // true

$valid = checkdate(1, 1, 2929); // true



// Correctly identify bad dates

$valid = checkdate(13, 1, 1996); // false

$valid = checkdate(4, 31, 2001); // false



// Correctly handles leap years

$valid = checkdate(2, 29, 1996); // true

$valid = checkdate(2, 29, 2001); // false