9.1 Displaying the Date or Time

The simplest display of date or time is telling your users what time it is. Use the date( ) or strftime( ) function as shown in Example 9-1.

Example 9-1. What time is it?

print 'strftime( ) says: ';
print strftime('%c');
print "\n";
print 'date( ) says:';
print date('r');

At noon on October 20, 2004, Example 9-1 prints:

strftime( ) says: Wed Oct 20 12:00:00 2004
date( ) says: Wed, 20 Oct 2004 12:00:00 -0400

Both strftime( ) and date( ) take two arguments. The first controls how the time or date string is formatted, and the second controls what time or date to use. If you leave out the second argument, as in Example 9-1, each uses the current time.

With date( ), individual letters in the format string translate into certain time values. Example 9-2 prints out a month, day, and year with date( ).

Example 9-2. Printing a formatted date string with date( )

print date('m/d/y');

At noon on October 20, 2004, Example 9-2 prints:

10/20/04

In Example 9-2, the m becomes the month (10), the d becomes the day of the month (20), and the y becomes the two-digit year (04). Because the slash is not a format character that date( ) understands, it is left alone in the string that date( ) returns.

With strftime( ), the things in the format string that get replaced by time and date values are set off by percent signs.^[1] Example 9-3 prints out a month, day, and year with strftime( ).

^[1] This makes strftime( ) format strings look like printf( ) format strings, but they're different. The modifiers that work with printf( ) don't work with strftime( ).

Example 9-3. Printing a formatted date string with strftime( )

print strftime('%m/%d/%y');

At noon on October 20, 2004, Example 9-3 prints:

10/20/04

In Example 9-3, the %m becomes the month, the %d becomes the day, and %y becomes the two-digit year.

Table 9-1 lists all of the special characters that date( ) and strftime( ) understand. The "Windows?" column indicates whether the character is supported by strftime( ) on Windows.

Table 9-1. strftime( ) and date( ) format characters

Type	strftime( )	date( )	Description	Range	Windows?
Hour	%H	H	Hour, numeric, 24-hour clock.	00-23	Yes
Hour	%I	h	Hour, numeric, 12-hour clock.	01-12	Yes
Hour	%k		Hour, numeric, 24-hour clock, leading zero as space.	0-23	No
Hour	%l		Hour, numeric, 12-hour clock, leading zero as space.	1-12	No
Hour	%p	A	A.M. or P.M. designation for current locale.		Yes
Hour	%P	a	a.m. or p.m. designation for current locale.		No
Hour		G	Hour, numeric, 24-hour clock, leading zero trimmed.	0-23	No
Hour		g	Hour, numeric, 12-hour clock, leading zero trimmed.	0-11	No
Minute	%M	i	Minute, numeric.	00-59	Yes
Second	%S	s	Second, numeric.	00-61[2]	Yes
Day	%d	d	Day of the month, numeric.	01-31	Yes
Day	%e		Day of the month, numeric, leading zero as space.	1-31	No
Day	%j	z	Day of the year, numeric.	001-366 for strftime( ), 0-365 for date( )	Yes
Day	%u		Weekday, numeric, 1 = = Monday.	1-7	No
Day	%w	w	Day of the week, numeric, 0 = = Sunday.	0-6	Yes
Day		j	Day of the month, numeric, leading zero trimmed.	1-31	No
Day		S	English ordinal suffix for day of the month, textual.	"st", "th", "nd", "rd"	No
Week	%a	D	Abbreviated weekday name, text for current locale.		Yes
Week	%A	l	Full weekday name, text for current locale.		Yes
Week	%U		Week number in the year, numeric, first Sunday is the first day of the first week.	00-53	Yes
Week	%V		ISO 8601:1988 week number in the year, numeric, week 1 is the first week that has at least four days in the current year, Monday is the first day of the week.	01-53	No
Week	%W		Week number in the year, numeric, first Monday is the first day of the first week.	00-53	Yes
Month	%B	F	Full month name, text for current locale.		Yes
Month	%b	M	Abbreviated month name, text for current locale.		Yes
Month	%h		Same as %b.		No
Month	%m	m	Month, numeric.	01-12	Yes
Month		n	Month, numeric, leading zero trimmed.	1-12	No
Month		t	Month length in days, numeric.	28, 29, 30, 31	No
Year	%C		Century, numeric.	00-99	No
Year	%g		Like %G, but without the century.	00-99	No
Year	%G		ISO 8601 year with century, numeric. The 4-digit year corresponding to the ISO week number. Same as %Y except if the ISO week number belongs to the previous or next year, that year is used instead.		No
Year	%y	y	Year without century, numeric.	00-99	Yes
Year	%Y	Y	Year, numeric, including century.		Yes
Year		L	Leap year flag (1 = = yes).	0, 1	No
Time zone	%z	O	Hour offset from GMT, +/-HHMM (e.g., -0400, +0230).	-1200-+1200	Yes, but acts like %Z
Time zone	%Z	T	Time zone or name or abbreviation, textual.		Yes
Time zone		I	Daylight Saving Time flag (1 = = yes).	0, 1	No
Time zone		Z	Seconds offset from GMT; west of GMT is negative, east of GMT is positive.	-43200-43200	No
Compound	%c		Standard date and time format for current locale.		Yes
Compound	%D		Same as %m/%d/%y.		No
Compound	%F		Same as %Y-%m-%d.		No
Compound	%r		Time in A.M. or P.M. notation for current locale.		No
Compound	%R		Time in 24-hour notation for current locale.		No
Compound	%T		Time in 24-hour notation (same as %H:%M:%S).		No
Compound	%x		Standard date format for current locale (without time).		Yes
Compound	%X		Standard time format for current locale (without date).		Yes
Compound		r	RFC 822 formatted date; i.e. "Thu, 21 Dec 2000 16:01:07 +0200".		No
Other	%s	U	Seconds since the epoch.		No
Other		B	Swatch Internet time.		No
Formatting	%%		Literal % character.		Yes
Formatting	%n		Newline character.		No
Formatting	%t		Tab character.		No

^[2] The range for seconds extends to 61 to account for leap seconds.

As just mentioned, to get date( ) or strftime( ) to print a formatted time string for a particular time, supply that time (as an epoch timestamp) as the second argument to either function. Example 9-4 prints out the time an hour from now. It uses the time( ) function, which returns the current epoch timestamp.

Example 9-4. Printing a formatted time string for a particular time

print 'strftime says( ): ';
print strftime('%I:%M:%S', time( ) + 60*60);
print "\n";
print 'date( ) says: ';
print date('h:i:s', time( ) + 60*60);

At noon on October 20, 2004, Example 9-4 prints:

strftime( ) says: 01:00:00
date( ) says: 01:00:00

At noon, time( ) + 60*60 equals the epoch timestamp for 1 p.m. (60*60 = 3600, the number of seconds in one hour.) The formatting characters used by strftime( ) and date( ) in Example 9-4 print the hour, minute, and second corresponding to the supplied epoch timestamp.

The date( ) and strftime( ) functions each have their strong points. If you are generating a formatted time or date string that has other text in it too, strftime( ) is better because you don't have to worry about letters without percent signs turning into time or date values. Example 9-5 shows how to use date( ) and strftime( ) to print a formatted date string like this. The version with strftime( ) is simpler.

Example 9-5. Printing a formatted time string with other text

print 'strftime( ) says: ';
print strftime('Today is %m/%d/%y and the time is %I:%M:%S');
print "\n";
print 'date( ) says: ';
print 'Today is ' . date('m/d/y') . ' and the time is ' . date('h:i:s');

At noon on October 20, 2004, Example 9-5 prints:

strftime( ) says: Today is 10/20/2004 and the time is 12:00:00
date( ) says: Today is 10/20/2004 and the time is 12:00:00

The date( ) function shines for different reasons. It supports some things that strftime( ) doesn't, such as a leap year indicator, a DST indicator, and trimming leading zeroes from some values. Furthermore, date( ) is a PHP-specific function. The strftime( ) PHP function relies on an underlying operating system function (also called strftime( )). That's why some format characters aren't supported on Windows. When you use date( ), it's guaranteed to work the same everywhere. Unless you need to put text that isn't format characters into the format string, choose date( ) over strftime( ).