Examples

Examples -- Learning by doing

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);
?>

Note: Date_Span works, unlike Date, internally with integers, which means that you have a precision of 32 bit or 68 years.

Converting timezones

Date can help you working with time zones. An array with all supported timezones can be retrieved by using 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";
}
?>