[edit] Abstract

Almost every data set contains one or more date or time informations. That may be a birthday in a Contact, start- and endtimes for events or a modification time of a arbitrary data set.

Several possible digital representations of time and date information and the facts of timeshift and different end user representations of these informations, can cause major problems when dealing with time and date information and are a frequent source of confusing bugs.

Therefore we maintain strict rules for dealing with these kind of datas to minimise the potential fault sources.

DateTime handling in eGroupWare 2.0

[edit] Database layer

As any modern database supports some kind of a dateTime data type, that format is to be used. This has the advantage, that time related stuff can be delegated to the database where it is computed more performant in most cases.

The timezone of the these informations is allways in server-time.

Some Database brands support automatic timezone conversion of dateTime data depending on the defined localistation of the client. Moreover some php database adapters also suppot such kind of transformations. We dont use any of those features. Thus the database connections are not made with any localisations and also the php database adopters are to be invoked without any localisation.

For the database compability with the current egw1.x series there are many UNIX timestamp representations in the database layer which are contained in big-int fields to store 64bit integers. The longterm goal is to convert those fields into the native database dateTime representations.

[edit] PHP application layer

Within the php application layer, we allways represent dateTime informations as Zend_Date objects in server-time. That means, on one hand the storage backend classes convert the backends native representations from and to Zend_Date objects in server-time, and on the other hand the frontend servers convert Zend_Date objects from an to the dateTime representation and timezones required by the client.

Example: An addressbook SQL query result comes up with a ISO 8601 formated string representing the birthday information of a contact in server-time (this is the case for native dateTime fields from the database). The Adressbook_Backend_SQL classe converts this into a Zend_Date Object when generating the correspontig Contact object and leaves the timezone untouched. All following code leaves this represetation as it is. At last the Addressbook_Json class converts this Zend_Date object into the ISO 8601 representation in user-time which is defined as the interface for the ext JS client.

[edit] Client layer

Different clients define different dateTime representations in their interfaces. As described above, thus the convertion to the clients representation is done in the server which serves the particular client.

[edit] Json

All dateTime information are represented in ISO 8601 at client time

Example PHP JSON Server:

// Zend_Date object "now" in servertime
$date = new Zend_Date();

// get clients timezone from framework, e.g. 'Europe/Berlin'
$timezone = Zend_Registry::get( 'userTimeZone' );

// get iso representation for JSON transport e.g. 2009-02-13T14:53:27+01:00
$isoString = $date->getIso( $timezone );

// create Zend_Date object from JSON iso transport
$date = new Zend_Date( $isoString, Zend_Date::ISO_8601, $timezone );

Example JS JSON Client:

 // Ext.Date object "now" in clienttime
 var date = new Date();

// get iso representation for client transport
var isoString = date.format( 'c' );

// create new Ext.Date object from JSON iso transport
var date = Date.parseDate( isoString, 'c' );

// automatic date conversion in Ext.data.Store objects
var s = new Ext.data.Store({
  ...
  fields: [{name: someDateField, type: 'date', format: 'c'}],
  ...
})