Handling of DateTime informations

From Tine 2.0 - Wiki

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 data to minimise the potential fault sources.

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 with more performance in most cases.

The timezone of the these informations is always in UTC.

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

PHP application layer

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

Tinebase_DateTime extends PHP natives DateTime Object with some convenience methods and handling for PHP versions < 5.3. More details about this can be found here

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

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.

Json

All dateTime information are represented in ISO 8601 at client time

Example PHP JSON Server:

// Tinebase_DateTime object "now" in UTC
$date = Tinebase_DateTime::now();

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

// set timezone of date to users timezone
$isoString = $date->setTimezone($timezone);

// get iso representation
$dateString =  $date->format('Y-m-d H:i:s');

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'}],
  ...
})