Example: Using the Date Class

As mentioned in Chapter 26, "Working with Dates and Times," the integer-based timestamp system used by PHP for dates and times, although very powerful for what it does, has a limitation in that it only supports existence between 1970 and early 2038. The ideal, of course, is a date and time system that supports a wider range of values.

The PEAR Date package does just that. It supports dates from the year 0 to 9999, and still supports fully localized values for days, months, and formats.

Installation

To get the Date package, execute the install command as follows:

 C:\PHP>pear install date downloading Date-1.4.3.tgz ... Starting to download Date-1.4.3.tgz (42,048 bytes) ....done: 28,972 bytes install ok: Date 1.4.3 

This class is installed in C:\PHP\PEAR on Windows machines and in /usr/local/lib/php on Unix servers.

Basic Use

To use this class, just include it in your PHP scripts as follows:

 require_once('Date.php'); 

After doing this, you can review the documentation for the Date class at http://pear.php.net/package/Date/docs to learn how to use it. The simplicity of the Date class means that you will soon be ready to write simple scripts such as the following:

 <?php require_once('Date.php'); $d = new Date('1841-12-18 15:25:48'); echo $d->format('%A %B %d, %Y, %R'); echo "<br/>\n"; setlocale(LC_ALL, "italian"); echo $d->format('%A %d %B, %Y, %R'); ?> 

This script takes a date and time and then prints them in both English and Italian. Upon first execution of this script, you might see the following:

 Strict Standards: var: Deprecated. Please use the   public/private/protected modifiers    in C:\PHP\PEAR\Date.php on line 76 

If you have your error_reporting value set to E_STRICT in php.ini or in your script, you might have a lot of trouble (as earlier) with PEAR, because most of the code in it is still written for PHP4. The easy way to get around this is to include the following before including any PHP4 classes:

 error_reporting(E_ALL);  // remove E_STRICT! 

The output from the simple example use of the PEAR Date class is this:

 Saturday December 18, 1841, 15:25 sabato 18 dicembre, 1841, 15:25 

Further Examples

This section examines how to implement via the Date class a few of the functions implemented for date/time arithmetic in Chapter 26. First, we write a function to see whether a date falls within a range specified by a start and end date. This uses the before and after methods on the Date class, which tell us, respectively, whether the Date object represents a time before or after the Date passed in as a parameter:

 function date_lies_within (   Date $in_test,   Date $in_start,    Date $in_end ) {   return ($in_start->before($in_test)           and ($in_end->after($in_test))); } 

Next we implement a function to see whether two date/time values are the same day:

 function same_day($in_d1, $in_d2) {   return ($in_d1->format('%Y-%m-%d')           == $in_d2->format('%Y-%m-%d')); } 

Finally, we look at a function to add a number of days to a given date/time value. Doing so requires the use of a new class, called the Date_Span class. This class represents a span of absolute time, such as 3 seconds, 4 weeks and 4 days, or 1,478 days. Generally, you create this class by passing two values to the constructor:

• The span measurement (as a string)

• A format string indicating what exactly is in that string

The format string has similar values to the format function on the Date class. For example:

 $ds = new Date_Span('5', '%H');          // 5 hours $ds = new Date_Span('10', '%D');         // 10 days $ds = new Date_Span('3500', '%s');       // 3500 seconds $ds = new Date_Span('1 12', '%D %H');    // 36 hours (1d 12h) 

You can also create a Date_Span class by passing it two Date objects. The span is taken to be the difference in time between these two values:

 $ds = new Date_Span($date1, $date2); 

To write our function to add days to a Date then, our function looks like this:

 function add_days_to_date($in_d1, $in_days) {   $d = new Date($in_d1);   $d->addSpan(new Date_Span("$in_days", '%d'));   return $d; } 

The addSpan method on the Date class is the one that does most of this work for us and modifies the object in place (as opposed to returning a new one and leaving the existing one untouched). There is also an analogous subtractSpan method:

 $d = new Date(); echo $d->format('%Y-%m-%d  %R<br/>'); $d->addSpan(new Date_Span('14', '%d')); echo $d->format('%Y-%m-%d  %R<br/>'); $d->subtractSpan(new Date_Span('21', '%d')); echo $d->format('%Y-%m-%d  %R<br/>'); 

The output of this looks similar to (depending on when you run it) the following:

 2005-11-23 13:49 2005-12-07 13:49 2005-11-16 13:49 

PEAR contains many extremely cool classes that are worth using in your web applications. Take some time to browse through them. You won't be disappointed.