The way you use the DateTime class is like any other: instantiate an object, and store it in a variable like this:

$date = new DateTime();

You can then apply any of the methods listed in Table 3-1 (apart from __construct(), which is called automatically when you instantiate an object) by using the -> operator. To format the date, use the format() method with the standard PHP date formatting characters like this (the code is in date_test_01.php in the ch3_exercises folder):

$date = new DateTime();
echo $date->format('l, F jS, Y'),

This creates a DateTime object representing the current date and time and displays it as shown in Figure 3-2.

Figure 3.2. DateTime::format() displays the date in the same way as the standard date() function.

If you're familiar with the date() function that's been around since PHP 4, you're probably wondering what's the point of using a DateTime object. After all, you can produce exactly the same output as in Figure 3-2 with the following code:

echo date('l, F jS, Y'),

It's much shorter and does exactly the same thing. Moreover, you need to use the same formatting characters, even if you choose the object-oriented approach.

The DateTime class is more useful when you're working with dates other than the current date and time. Rather than juggle several different functions, such as mktime(), strtotime(), strftime(), and date(), everything is handled by the object and its methods. For example, you can display next Thursday's date by changing the previous code like this (it's in date_test_02.php):

$date = new DateTime('next Thursday');
echo $date->format('l, F jS, Y'),

This produces the output shown in Figure 3-3 (obviously, the actual date will depend on when you run the script).

Figure 3.3. The DateTime class makes it easy to create dates based on natural language.

You can also use any of the eleven constants defined by the class to format a DateTime object. Because they are class constants, you need to prefix them with the class name and the scope resolution operator like this:

echo $date->format(DateTime::ATOM);

Figure 3-4 shows the output of each constant as applied to the same DateTime object. You can test the code yourself in date_test_03.php. Not only will the date and time be different, depending on when you view it, but the time zone offset will also change if your server is in a different part of the world.

Figure 3.4. The same DateTime object as formatted by each of the class constants

To change the date stored by a DateTime object after it has been created, you use DateTime::modify() with a natural language expression, or DateTime::setDate() with an actual date like this:

$date->modify('+2 months'),  // adds two months to existing date
$date->setDate(2008, 8, 8);  // sets date to August 8, 2008

An important feature of the object-oriented way of handling dates in PHP is the ability to set the time zone of a DateTime object. You can set the time zone explicitly by passing a DateTimeZone object as the second argument to the constructor. I'll explain how to do this in "Using the DateTimeZone class" a little later in the chapter. However, this usually isn't necessary, as DateTime objects use the default time zone for your server.

As its name suggests, the World Wide Web is international, and one of the biggest frustrations of handling dates in PHP scripts arises when your server is in a different time zone from your target audience. Since PHP 5.1, this is no longer a problem. The server administrator should set the default time zone in php.ini, using the date.timezone directive. You can check the value on your server by running phpinfo() and scrolling down to the date section. As you can see from Figure 3-5, Default timezone on my server is set to Europe/London.

Figure 3.5. It's a good idea to check the time zone being used by your server.

There are far too many time zones to list here, but you can find a list of all time zones supported by PHP at http://docs.php.net/manual/en/timezones.php. If the default time zone on your server doesn't suit your needs, never fear. There are several ways to reset it. If the server is under your own control, the best way to do it is to change the value of date.timezone in php.ini, and restart your web server. If you're on shared hosting and don't have access to php.ini, you can choose from one of the following methods (replace Europe/London in the following examples with the appropriate time zone from among those listed at the previous URL).

Resetting the time zone in .htaccess

If your server runs on Apache, and your hosting company has set the correct permissions for you to use an .htaccess file, add the following command to the .htaccess file in your site root (see http://en.wikipedia.org/wiki/Htaccess if you're not familiar with .htaccess files):

php_value date.timezone 'Europe/London'

This changes the default time zone for every page on the site.

Resetting the time zone in individual scripts

If you can't change the configuration for the whole site, or need to change the time zone only for a specific script, add the following line of code before using any date functions:

ini_set('date.timezone', 'Europe/London'),

Alternatively, use this:

date_default_timezone_set('Europe/London'),

Both do exactly the same. It doesn't matter which you use. It's a good idea to put configuration changes like this at the top of the script so that they are immediately obvious and available.

The DateTimeZone class is a close companion of the DateTime class, and it gives you much greater control over the use of time zones, allowing you to create objects to represent times in different parts of the world, regardless of the default time zone for your server. Using the Reflection API to examine the DateTimeZone class with the following code (it's also in inspect_DateTimeZone.php) produces the output shown in Figure 3-6:

Reflection::export(new ReflectionClass('DateTimeZone'));

Figure 3.6. The details of the DateTimeZone class exposed by the Reflection API

As you can see from the output of the Reflection API, the DateTimeZone class has no constants or properties. It also has only six methods, but two of them are static. Table 3-2 describes each method.

Figure 3.7. DateTimeZone::getTransitions() provides historical and future data about daylight saving time for all time zones.

A quick glance at Table 3-2 reveals that most methods of the DateTimeZone class are rather specialized, so I don't intend to dwell on them at length. Use the files listed in Table 3-2 to see how they work. Take particular note of how DateTimeZone::getOffset() works in date_test_06.php. It uses the current time in New York to work out the time difference between New York and Los Angeles. The code is fully commented to explain how it works, and you can experiment by changing the time zone identifiers at the beginning of the script.

The most common use of the DateTimeZone class is to alter the time zone of a DateTime object. First, you create a DateTimeZone object by passing the time zone identifier to the constructor. Then you pass the DateTimeZone object as the second argument to the DateTime constructor like this (the code is in date_test_08.php):

$Tokyo = new DateTimeZone('Asia/Tokyo'),
$now = new DateTime('now', $Tokyo);
echo "<p>In Tokyo, it's " . $now->format('g:i A') . '</p>';

This displays the current date and time in Tokyo, regardless of the time zone on your own server.

You can also use a DateTimeZone object to change the time zone of an existing DateTime object by passing it as an argument to DateTime::setTimezone(). The following code (it's also in date_test_09.php) displays the current time in different parts of the world by resetting the time zone of the DateTime object stored as $now:

// create a DateTime object
$now = new DateTime();
echo '<p>My local time is ' . $now->format('l, g:i A') . '</p>';

// create DateTimeZone objects for various places
$Katmandu = new DateTimeZone('Asia/Katmandu'),
$Moscow = new DateTimeZone('Europe/Moscow'),
$Timbuktu = new DateTimeZone('Africa/Timbuktu'),
$Chicago = new DateTimeZone('America/Chicago'),
$Fiji = new DateTimeZone('Pacific/Fiji'),

// reset the time zone for the DateTime object to each time zone in turn
$now->setTimezone($Katmandu);
echo "<p>In Katmandu, it's " . $now->format('l, g:i A') . '</p>';
$now->setTimezone($Moscow);
echo "<p>In Moscow, it's " . $now->format('l, g:i A') . '</p>';
$now->setTimezone($Timbuktu);
echo "<p>In Timbuktu, it's " . $now->format('l, g:i A') . '</p>';
$now->setTimezone($Chicago);
echo "<p>In Chicago, it's " . $now->format('l, g:i A') . '</p>';
$now->setTimezone($Fiji);
echo "<p>And in Fiji, it's " . $now->format('l, g:i A') . '</p>';

This script produces output similar to Figure 3-8.

Figure 3.8. The DateTimeZone class makes it easy to display the time in different parts of the world.

This example uses the current time, but you can specify the date and time of a DateTime object, so using the DateTime and DateTimeZone classes in combination with each other makes it very easy to display the time of live events on a web site, showing the local time in various parts of the world where your target audience is likely to be. Remember, though, that if you need to maintain a reference to separate time zones in different parts of a script, it's better to create a DateTime object for each one like this:

$myTime = new DateTime();
$westCoast = new DateTimeZone('America/Los_Angeles'),
$LAtime = new DateTime('now', $westCoast);

Now that you have got a good idea of the DateTime and DateTimeZone classes, you can set about deciding how to design a custom class that builds on the existing functionality.

This is the full listing for setMDY(), which accepts dates in the standard American format MM/DD/YYYY.

public function setMDY($USDate)
{
  $dateParts = preg_split('{[-/ :.]}', $USDate);
  if (!is_array($dateParts) || count($dateParts) != 3) {
    throw new Exception('setMDY() expects a date as "MM/DD/YYYY".'),
  }
  $this->setDate($dateParts[2], $dateParts[0], $dateParts[1]);
}

The first line inside the setMDY() method uses preg_split() to break the input into an array. I have used preg_split() instead of explode(), because it accepts a regular expression as the first argument. The regular expression {[-/ :.]} splits the input on any of the following characters: dash, forward slash, single space, colon, or period. This permits not only MM/DD/YYYY, but variations, such as MM-DD-YYYY or MM:DD:YYYY.

As long as $dateParts is an array with three elements, the date parts are passed internally to the overridden setDate() method for the rest of the process. If there's anything wrong with the data, it's the responsibility of setDate() to throw an exception.

The setDMY() method is identical to setMDY(), except that it passes the elements of the $dateParts array to setDate() in a different order to take account of the DD/MM/YYYY format commonly used in Europe and many other parts of the world. The full listing looks like this:

public function setDMY($EuroDate)
{
  $dateParts = preg_split('{[-/ :.]}', $EuroDate);
  if (!is_array($dateParts) || count($dateParts) != 3) {
    throw new Exception('setDMY() expects a date as "DD/MM/YYYY".'),
  }
  $this->setDate($dateParts[2], $dateParts[1], $dateParts[0]);
}

This works exactly the same as the previous two methods. Although MySQL uses only a dash as the separator between date parts, I have left the regular expression unchanged, so that the setFromMySQL() method can be used with dates from other sources that follow the same ISO format as MySQL. The full listing follows:

public function setFromMySQL($MySQLDate)
{
  $dateParts = preg_split('{[-/ :.]}', $MySQLDate);
  if (!is_array($dateParts) || count($dateParts) != 3) {
    throw new Exception('setFromMySQL() expects a date as "YYYY-MM-DD".'),
  }
    $this->setDate($dateParts[0], $dateParts[1], $dateParts[2]);
}

Now let's turn to formatting dates, starting with the most commonly used formats.

Another problem with DateTime::modify() and strtotime() is that they accept any string input. If the string can be parsed into a date expression, everything works fine; but if PHP can't make sense of the string, it generates an error. So, it's a good idea to cut down the margin for error as much as possible. The four new methods, addDays(), subDays(), addWeeks(), and subWeeks() accept only a number; creation of the string to be passed to the parent modify() method is handled internally. The following listing shows all four methods:

public function addDays($numDays)
{
  if (!is_numeric($numDays) || $numDays < 1) {
    throw new Exception('addDays() expects a positive integer.'),
  }
  parent::modify('+' . intval($numDays) . ' days'),
}

public function subDays($numDays)
{
  if (!is_numeric($numDays)) {
    throw new Exception('subDays() expects an integer.'),
  }
  parent::modify('-' . abs(intval($numDays)) . ' days'),
}

public function addWeeks($numWeeks)
{
  if (!is_numeric($numWeeks) || $numWeeks < 1) {
    throw new Exception('addWeeks() expects a positive integer.'),
  }
  parent::modify('+' . intval($numWeeks) . ' weeks'),
}

public function subWeeks($numWeeks)
{
  if (!is_numeric($numWeeks)) {
    throw new Exception('subWeeks() expects an integer.'),
  }
  parent::modify('-' . abs(intval($numWeeks)) . ' weeks'),
}

Each method follows the same pattern. It begins by checking whether the argument passed to it is numeric. In the case of addDays() and addWeeks(), I have also checked whether the number is less than 1. I did this because it seems to make little sense to accept a negative number in a method designed to add days or weeks. For some time, I toyed with the idea of creating just two methods (one each for days and weeks) and getting the same method to add or subtract depending on whether the number is positive or negative. In the end, I decided that an explicit approach was cleaner.

Since is_numeric() accepts floating point numbers, I pass the number to intval() to make sure that only an integer is incorporated into the string passed to parent::modify().

Another design problem that I wrestled with for some time was whether to accept negative numbers as arguments to subDays() and subWeeks(). The names of the methods indicate that they subtract a specified number of days or weeks, so most people are likely to insert a positive number. However, you could argue that a negative number is just as logical. One solution is to throw an exception if a negative number is submitted. In the end, I opted to accept either negative or positive numbers, but to treat them as if they mean the same thing. In other words, to subtract 3 days from the date regardless of whether 3 or −3 is passed to subDays(). So, the string built inside subDays() and subWeeks() uses abs() and intval() as nested functions like this:

'-' . abs(intval($numWeeks)) . ' weeks'

If you're not familiar with nesting functions like this, what happens is that the innermost function is processed first, and the result is then processed by the outer function. So, intval($numWeeks) converts $numWeeks to an integer, and abs() converts the result to its absolute value (in other words, it turns a negative number into a positive one). So, if the value passed to subWeeks() is −3.25, intval() converts $numWeeks to −3, and abs() subsequently converts it to 3. The resulting string passed to parent::modify() is '-3 weeks'.

You can test these methods in Pos_Date_test_06.php through Pos_Date_test_09.php in the download files.

A month can be anything from 28 to 31 days in length, so it's impossible to calculate the number of seconds you need to add to a Unix timestamp—at least, not without some fiendishly complicated formula. The solution I have come up with is to add the number of months to the current month. If it comes to 12 or less, you have the new month number. If it's more than 12, you need to calculate the new month and year. Finally, you need to work out if the resulting date is valid. If it isn't, it means you have ended up with a date like February 30, so you need to find the last day of the new month, taking into account the vagaries of leap years.

It's not as complicated as it sounds, but before diving into the PHP code, it's easier to understand the process with some real figures.

Let's take February 29, 2008, as the starting date. In terms of the Pos_Date properties, that looks like this:

$_year = 2008;
$_month = 2;
$_day = 29;

Add 9 months:

$_month += 9;  // result is 11

The result is 11 (November). This is less than 12, so the year remains the same. November 29 is a valid date, so the calculation is simple.

Instead of 9 months, add 12:

$_month += 12;  // result is 14

There isn't a fourteenth month in a year, so you need to calculate both the month and the year. To get the new month, use modulo division by 12 like this:

14 % 12;  // result is 2

Modulo returns the remainder of a division, so the new month is 2 (February). To calculate how many years to add, divide 14 by 12 and round down to the nearest whole number using floor() like this:

$_year += floor(14 / 12);  // adds 1 to the current year

This works fine for every month except December. To understand why, add 22 months to the starting date:

$_month += 22;  // result is 24
$remainder = 24 % 12;  // result is 0

Dividing 24 by 12 produces a remainder of 0. Not only is there no month 0, division by 12 produces the wrong year as this calculation shows:

$_year += floor(24 / 12);  // adds 2 to the current year

Any multiple of 12 produces a whole number, and since there's nothing to round down, the result is always 1 greater than you want. Adding 2 to the year produces 2010; but 22 months from the starting date should be December 29, 2009. So, you need to subtract 1 from the year whenever the calculation produces a date in December.

Finally, you need to check that the resulting date is valid. Adding 12 months to the starting date produces February 29, 2009, but since 2009 isn't a leap year, you need to adjust the result to the last day of the month.

With all that in mind, you can map out the internal logic for addMonths() like this:

The full listing for addMonths(), together with inline comments, looks like this:

public function addMonths($numMonths)
{
  if (!is_numeric($numMonths) || $numMonths < 1) {
    throw new Exception('addMonths() expects a positive integer.'),
  }
  $numMonths = (int) $numMonths;
  // Add the months to the current month number.
  $newValue = $this->_month + $numMonths;
  // If the new value is less than or equal to 12, the year
  // doesn't change, so just assign the new value to the month.
  if ($newValue <= 12) {
    $this->_month = $newValue;
  } else {
    // A new value greater than 12 means calculating both
    // the month and the year. Calculating the year is
    // different for December, so do modulo division
    // by 12 on the new value. If the remainder is not 0,
    // the new month is not December.
    $notDecember = $newValue % 12;
    if ($notDecember) {
      // The remainder of the modulo division is the new month.
      $this->_month = $notDecember;
      // Divide the new value by 12 and round down to get the
      // number of years to add.
      $this->_year += floor($newValue / 12);
    } else {
      // The new month must be December
      $this->_month = 12;
      $this->_year += ($newValue / 12) - 1;
    }
  }
  $this->checkLastDayOfMonth();
  parent::setDate($this->_year, $this->_month, $this->_day);
}

The preceding explanation and the inline comments explain most of what's going on here. The result of the modulo division is saved as $notDecember and then used to control a conditional statement. Dividing $newValue by 12 produces a remainder for any month except December. Since PHP treats any number other than 0 as true, the first half of the conditional statement will be executed. If there's no remainder, $notDecember is 0, which PHP treats as false, so the else clause is executed instead.

All that remains to explain are the last two lines, the first of which calls an internal method called checkLastDayOfMonth(). This now needs to be defined.

Adjusting the last day of the month

The reason for not using DateTime::modify() is to prevent the date from being shifted to the first of the following month, so you need to check the validity of the resulting date before passing it to setDate() and reset the value of $_day to the last day of the month, if necessary. That operation is performed by the checkLastDayofMonth() method, which looks like this:

final protected function checkLastDayOfMonth()
{
  if (!checkdate($this->_month, $this->_day, $this->_year)) {
    $use30 = array(4 , 6 , 9 , 11);
    if (in_array($this->_month, $use30)) {
      $this->_day = 30;
    } else {
      $this->_day = $this->isLeap() ? 29 : 28;
    }
  }
}

The first thing to note about this method is that, unlike all other methods defined so far, this is both final and protected. This prevents anyone from either calling it directly or overriding it in a subclass. The reason I don't want it to be called directly is because it changes the value of the $_day property, so could result in arbitrary changes to your code. A protected method can be called only inside the class itself or a subclass. If it results in arbitrary changes to the date being stored, the only person to blame is yourself for making a mistake in the code.

The method passes the values of $_month, $_day, and $_year to checkdate(), which as you have seen before, returns false if the date is nonexistent. If the date is OK, the method does nothing. However, if checkdate() returns false, the method examines the value of $_month by comparing it with the $use30 array. April (4), June (6), September (9), and November (11) all have 30 days. If the month is one of these, $_day is set to 30.

If the month isn't in the $use30 array, it can only be February. In most years, the last day of the month will be 28, but in leap year, it's 29. The task of checking whether it's a leap year is handed off to another method called isLeap(), which returns true or false. If isLeap() returns true, the conditional operator sets $_day to 29. Otherwise, it's set to 28.

Checking for leap year

Leap years occur every four years on years that are wholly divisible by 4. The exception is that years divisible by 100 are not leap years unless they are also divisible by 400. Translating that formula into a conditional statement that returns true or false produces the following method:

public function isLeap()
{
  if ($this->_year % 400 == 0 || ($this->_year % 4 == 0 && 

$this->_year % 100 != 0)) {
    return true;
  } else {
    return false;
  }
}

I've made this method public because it doesn't affect any internal properties and could be quite useful when working with Pos_Date objects. It bases its calculation on the value of $_year, so doesn't rely on the date being set to February.

Because checkLastDayOfMonth() has already checked the validity of the date, and the values of $_year, $_month, and $_day have already been adjusted, they can be passed directly to the parent setDate() method to save a little processing time.

Figure 3-14 shows the different results produced by Pos_Date::addMonths() and DateTime::modify() when simply changing the month number would produce an invalid date (the code is in Pos_Date_test_10.php).

Figure 3.14. The addMonths() method adjusts the date automatically to the last day of the month if necessary.

Subtracting months requires similar logic. You start by subtracting the number of months from the current month number. If the result is greater than zero, the calculation is easy: you're still in the same year, and the result is the new month number. However, if you end up with 0 or a negative number, you've gone back to a previous year.

Let's take the same starting date as before, February 29, 2008. Subtract two months:

$_month -= 2;  // result is 0

It's easy to work out in your head that subtracting two months from February 29, 2008, results in December 29, 2007. What about subtracting three months? That brings you to November, and a month number of −1. Deduct four months, and you get October and a month number of −2. Hmm, a pattern is forming here that should be familiar to anyone who has worked with PHP for some time. If you remove the minus signs, you get a zero-based array. So, that's the solution: create an array of month numbers in reverse, and use the absolute value of deducting the number of months from the original month number as the array key. You could type out all the numbers like this:

$months = array(12 , 11 , 10 , 9 , 8 , 7 , 6 , 5 , 4 , 3 , 2 , 1);

However, it's much simpler to use the range() function, which takes two arguments and creates an array of integers or characters from the first argument to the second, inclusive. If the first argument is greater than the second one, the values in the array are in descending order. The following line of code produces the same result as the previous one:

$months = range(12, 1);

PHP arrays begin from 0, so $months[0] is 12, $months[1] is 11, and so on.

Also, because you're working in reverse from addMonths(), the year calculations round up, rather than down.

The full listing follows:

public function subMonths($numMonths)
{
  if (!is_numeric($numMonths)) {
    throw new Exception('addMonths() expects an integer.'),
  }
  $numMonths = abs(intval($numMonths));
  // Subtract the months from the current month number.
  $newValue = $this->_month - $numMonths;
  // If the result is greater than 0, it's still the same year,
  // and you can assign the new value to the month.
  if ($newValue > 0) {
    $this->_month = $newValue;
  } else {
    // Create an array of the months in reverse.
    $months = range(12 , 1);
    // Get the absolute value of $newValue.
    $newValue = abs($newValue);
    // Get the array position of the resulting month.
    $monthPosition = $newValue % 12;
    $this->_month = $months[$monthPosition];
    // Arrays begin at 0, so if $monthPosition is 0,
    // it must be December.
    if ($monthPosition) {
      $this->_year -= ceil($newValue / 12);
    } else {

$this->_year -= ceil($newValue / 12) + 1;
    }
  }
  $this->checkLastDayOfMonth();
  parent::setDate($this->_year, $this->_month, $this->_day);
}

As Figure 3-15 shows, using DateTime::modify() can produce radically unexpected results with some date calculations (the code is in Pos_Date_test_11.php). Pos_Date::subMonths() gives the right answer.

Figure 3.15. The subMonths() method correctly identifies the last day of the month when appropriate.

The code for addYears() and subYears() needs very little explanation. Changing the year simply involves adding or subtracting a number from $_year. The only date that causes a problem is February 29, but that's easily dealt with by calling checkLastDayOfMonth() before passing the $_year, $_month, and $_day properties to parent::setDate(). The full listing follows:

public function addYears($numYears)
{
  if (!is_numeric($numYears) || $numYears < 1) {
    throw new Exception('addYears() expects a positive integer.'),
  }
  $this->_year += (int) $numYears;
  $this->checkLastDayOfMonth();
  parent::setDate($this->_year, $this->_month, $this->_day);
}

public function subYears($numYears)
{
  if (!is_numeric($numYears)) {
    throw new Exception('subYears() expects an integer.'),
  }

$this->_year -= abs(intval($numYears));
  $this->checkLastDayOfMonth();
  parent::setDate($this->_year, $this->_month, $this->_day);
}

You can see examples of both methods in action in Pos_Date_test_12.php and Pos_Date_test_13.php.

MySQL made calculating the number of days between two dates very easy with the introduction of the DATEDIFF() function in version 4.1.1. With PHP, though, you still need to do the calculation with Unix timestamps. The Pos_Date::dateDiff() method acts as a wrapper for this calculation. It takes two arguments, both Pos_Date objects representing the start date and the end date. Both dates are used to create Unix timestamps with gmmktime(). The difference in seconds is divided by 60 × 60 × 24 before being returned. The timestamps are set to midnight UTC to avoid problems with daylight saving time and make sure that deducting one from the other results in an exact number of days. If the date in the first argument is earlier than the second, a positive number is returned. If it's later, a negative number is returned. The code for the method looks like this:

static public function dateDiff(Pos_Date $startDate, Pos_Date $endDate)
{
  $start = gmmktime(0, 0, 0, $startDate->_month, $startDate->_day, 

$startDate->_year);
  $end = gmmktime(0, 0, 0, $endDate->_month, $endDate->_day, 

$endDate->_year);
  return ($end - $start) / (60 * 60 * 24);
}

An important thing to note about this method definition is that it's prefixed with the static keyword. This turns it into a static (or class) method. Instead of applying the method to a Pos_Date object, you call it directly using the class name and the scope resolution operator like this:

Pos_Date::dateDiff($argument1, $argument2);

The other thing to note is that the argument block uses type hinting (see Chapter 2 for details). Both arguments must be Pos_Date objects. If you try to pass anything else as an argument, the method throws an exception.

The following code (in Pos_Date_test_14.php) shows an example of how Pos_Date::dateDiff() might be used:

require_once '../Pos/Date.php';
try {
  // create two Pos_Date objects
  $now = new Pos_Date();
  $newYear = new Pos_Date();
  // set one of them to January 1, 2009
  $newYear->setDate(2009, 1, 1);

// calculate the number of days
  $diff = Pos_Date::dateDiff($now, $newYear);
  $unit = abs($diff) > 1 ? 'days' : 'day';
  if ($diff == 0) {
      echo 'Happy New Year!';
  } elseif ($diff > 0) {
      echo "$diff $unit left till 2009";
  } else {
      echo abs($diff) . " $unit since the beginning of 2009";
  }
} catch (Exception $e) {
  echo $e;
}

This method poses another design dilemma. I have made it static because it works on two different Pos_Date objects. It also gives me an opportunity to demonstrate a practical example of creating and using a static method. You could argue, however, that it would be much simpler to compare two dates by passing one as an argument to the other. Both approaches are perfectly valid.

As an exercise, you might like to try your hand at modifying dateDiff() so that it works as an ordinary public method. The alternative solution is defined as dateDiff2() in Date.php, and Pos_Date_test_15.php demonstrates how it's used.