Recipe 3.16. Using Dates Outside the Range of an Epoch Timestamp

3.16.1. Problem

You want to use dates that are outside the range of what a 32-bit epoch timestamp can handle: roughly before 1901 or after 2038.

3.16.2. Solution

Use the PEAR Date_Calc class, which can handle dates from January 1, 1 CE to December 31, 9999 CE. Example 3-45 prints formatted dates for two days in the 9th century CE.

Using Date_Calc

<?php require_once 'Date/Calc.php'; // April 17, 1790 $date = Date_Calc::dateFormat( 17, 4, 1790, '%A %B %e, %Y'); print "Benjamin Franklin died on $date."; ?>

Example 3-45 prints:

Benjamin Franklin died on Saturday April 17, 1790.

3.16.3. Discussion

Because Date_Calc uses its own internal representation for dates, it's not subject to the limits of storing an epoch timestamp in a 32-bit integer. Its dateFormat( ) method works similarly to strftime( )'it turns a format string into a formatted date and time string. Table 3-7 lists the formatting characters that dateFormat( ) understands.

Table Formatting characters for Date_Calc::dateFormat( )

Character	Description
%d	Day of month, with leading 0
%e	Day of month, no leading 0
%w	Day of week, no leading 0, Sunday is 0
%j	Day of year, with leading 0
%E	Day count according to internal Date_Calc epoch
%a	Weekday name, short
%A	Weekday name, full
%U	Week number of current year
%m	Month number, no leading 0, January is 1
%b	Month name, short
%B	Month name, long
%y	Year, 2-digit with leading 0
%Y	Year, 4-digit with leading 0
%n	Newline
%t	Tab
%%	%

Date_Calc makes it easy to work with a wide range of Gregorian calendar dates, but it does not have comprehensive knowledge of the religious, political, and cultural factors that have caused modification to the calendar over time.

3.16.4. See Also

The PEAR Date package at http://pear.php.net/package/Date. The tip of the calendar-changing-over-time-wackiness iceberg is explored at http://en.wikipedia.org/wiki/Old_Style_and_New_Style_dates.