Manual

PEAR Date is a generic class to represent and work with dates. It does not use timestamps which means it can be used for dates before 1970 and after 2038. The class provides methods to convert a date in different formats, calculate differences, weekdays and more.

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

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";
}
?>

Basics

Basics – How to get information

Introduction

The auto-generated API documentation is very valuable to get information about this packages' methods and which parameters they require. But of course you first need to have an overview about the abilities of the class.

Getting data

There are a number of simple getter methods that let you retrieve single pieces of a date currently set.

Date does also have some advanced methods to obtain data from it.

Date::getDayName() returns the name of the day in short (Mon) or long form (Monday)
Date::getMonthName() returns the name of the month in short (Jan) or long form (January)
Date::getDayOfWeek() calculates the number of the day in the week (0-6, Sunday being 0)
Date::getWeekOfYear() returns the week number of this date
Date::getQuarterOfYear()

Navigating between dates

The following method all return a new date object.

You can also do excact calculations by adding and subtracting intervals. The *Span methods require a Date_Span object to be passed as only parameter while the others take a number representing seconds.

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!