Examples
Introduction
Following the saying "learning by doing", we start with some examples.
The first step to work with the class is to instantiate a Date, object.
Creating a Date object
<?php
require_once 'Date.php';
//without parameter == now
$now = new Date();
//pass a string in ISO format
$longAgo = new Date('1813-02-23T05:34:23');
//create a Date object from a PHP unix timestamp
$timestamp = time();
$nearlyNow = new Date($timestamp);
//make a copy of an existing Date object
$copyDate = new Date($longAgo);
?>
After finishing your work with the date object, you probably want to have it back. This can be done in different ways, for example by using getTime() or getDate()
Getting the date in different formats
<?php
require_once 'Date.php';
$now = new Date();
//UNIX timestamp: 1183054688
echo $now->getTime();
//ISO formatted date: 2007-06-28 20:18:08
echo $now->getDate();
?>
Date has a lot more methods to output your date, but that is subject of a later chapter.
Now that we know how to create a Date instance, we'll do some easy tasks.
Calculating a time difference
You often have the task to know which time span lies between two dates. With Date, this is easy to accomplish. First we use setFromDateDiff() on a fresh Date_Span object and then toDays() to get the exact number of days between the two dates.
Calculating a time span
<?php
require_once 'Date.php';
$someDate = new Date('1813-02-23T05:34:23');
$otherDate = new Date('1789-12-21T18:23:42');
$span = new Date_Span();
$span->setFromDateDiff($someDate, $otherDate);
//time span in days: 8463,46575231
echo $span->toDays();
//time span in full years: 23
echo (int)($span->toDays() / 365);
?>
Date_Span works, unlike Date, internally with integers, which means that you have a precision of 32 bit or ~68 years. Date span objects with more that 67 years will lead to unexpected results!
Converting timezones
Date can help you working with time zones. An array with all supported timezones can be retrieved by using Date_Timezone::getAvailableIDs(), statically as in $list = Date_TimeZone::getAvailableIDs();.
convertTZ converts the Date object's
internal settings to the given time zone.
Using
format()
you can display the timezone
setting. With Date_TimeZone's
getDefault method the default time
zone for this computer can be obtained.
Converting timezones
<?php
require_once 'Date.php';
//assume it's 2007-06-28 18:42:12
$now = new Date();
$timezone = new Date_TimeZone('Australia/Adelaide');
//convert the date object to the timezone
$now->convertTZ($timezone);
//will give you: 2007-06-29 02:12:12
echo $now->getDate();
//now with timezone: 2007-06-29 02:12:12+09:30
echo $now->format('%Y-%m-%d %H:%M:%S%O');
//switch back
$defaultZone = Date_TimeZone::getDefault();
$now->convertTZ($defaultZone);
//we have our normal zone now: 2007-06-28 18:42:12+02:00
echo $now->format('%Y-%m-%d %H:%M:%S%O');
?>
Sorting an array of dates
Once you have an array of Date objects, you might want to sort it. The class provides a static method compare() that helps with this.
Sorting dates
<?php
require_once 'Date.php';
$dates = array(
new Date('1813-02-23T05:34:23'),
new Date(),
new Date('1714-12-21T18:23:42'),
);
usort($dates, array('Date', 'compare'));
/*
* prints the dates correctly sorted:
* 1714-12-21 18:23:42
* 1813-02-23 05:34:23
* 2007-06-28 20:59:39
*/
foreach ($dates as $date) {
echo $date->getDate() . "\n";
}
?>