Recent Changes - Search:

Documents

Community

Related Projects

Powered by PmWiki

Date/time handling

Since RC2, HessianPHP can now serialize and deserialize date and time data using a simple method that allows to use any class that can handle timestamps to consruct 'Date' type of objects.

DateTime class

By default, HessianPHP comes with a very simple yet effective class called DateTime with the following structure.

class DateTime
Fields:

  • day
  • month
  • year
  • hour
  • minute
  • second
  • weekDay

Functions:

  • function DateTime($date='now')
  • function setTimestamp($ts)
  • function sync()
  • function asTime()
  • function asDate()
  • function getDateTime()
  • function getTimestamp()
  • function getWeekDay()
  • function daysInMonth()
  • function isBefore($time)
  • function isAfter($time)
  • function equals($time)
  • function dateDiff(&$other)
  • function compare($time1,$time2)
  • function monthName($value=null)
  • function findTimestamp($dateObj)
  • function add($part,$num=1)
  • function sub($part,$num=1)
  • function substract($part,$num=1)
  • function __toString()

...more

DateTime uses many standard PHP date/time functions so it can be constructed from a string, a timestamp or another DateTime object.

This class is also overloaded so you can perform operations such as add and sub easily.

Here are some usage examples:

// Create a new DateTime object

$date1 = new DateTime('2004-09-06 8:00:00');
$date2 = new DateTime('2005-10-12 9:00:00');
$date3 = new DateTime($date1); // safe copy
$date4 = $date2->asTime(); // extracts only the Time portions of DateTime

// Compare dates

echo $date1->isBefore($date2);
echo $date2->isAfter($date1);
echo $date1->equals($date3);
echo DateTime::compare($date1,$date2);

// A new instance with the value of 'now'

$now = new DateTime();

// Some basic operations

$now->add('minute',5);
$now->sub('hour',12);
$now->substract('second',3); // an alias of sub
$now->add('year',5);

// using the overloaded versions

$now->addYears(5); 
$now->subMonths(5);

// Display operations
echo $now->getDateTime();
echo $now->getDate();
echo $now->getTime();

echo $now->monthName();
echo $now->monthName($date1);
echo DateTime::monthName($now);
echo $now->strftime("%V,%G,%Y"); // uses strftime in this object's timestamp

// Calculate differences

print_r( $date1->dateDiff($date2) );


One very useful function is dateDiff() which returns an associative array with the differences between two dates like how many days are between two dates and such.

You can directly access fields of the object to perform operations such as $now->day++ but is recommended to use the functions to alter the objects because they automatically synchronize the internal timestamp avoiding to have incorrect values.

For more information about the functions in this class, please review the API documents or look at the code directly.

Change Date implementations: DateProvider

(Thanks Cedric Veilleux for the idea)

Although DateTime objects can be good enough for many situations, you might want to use a class of your own or another library, such as PEAR::Date. The only requirement is that your custom Date class can return and be constructed from an standard UNIX timestamp. Take a look at DateTime.php in the /dist folder for an example.

By default, HessianPHP defines a DefaultDateProvider class that interacts with the parser and the writer components to create DateTime objects when needed, but you can create your own DateProvider to use your class too by creating a class that implements these three functions:

  • isDateObject($object) : tells the parser if an object is to be treated as a timestamp container.
  • readDate($timestamp) : returns a new instance of the Date object from a timestamp
  • writeDate($dateobj) : returns the timestamp extracted from a Date object

Now, lets supose you want to use PEAR:Date as your main Date handling object, first, create a class such as this:

class PearDateProvider{

	function isDateObject($object){
		return is_a($object,'Date');
	}

	function readDate($timestamp){
		return new Date($timestamp / 1000);
	}

	function writeDate($dateobj){
		$ts = $dateobj->getTime();
		return $ts * 1000;
	}
}

Then, register a new object with the platform with the following call:

Hessian::setDateProvider(new PearDateProvider());

Now, every Date object passed to a remote call will be interpreted as a Hessian timestamp and every incoming timestamp will be turned into a PEAR Date object.

IMPORTANT: This will affect both HessianPHP clients and services.

A few things about this example: First, note the use of the is_a() native PHP function which simply tells if an object belongs to a class. In PHP 5, this can also be achieved by using the new is_a operator.

Second, because of PHP's internal timestamp format which is different from other platforms, you need to divide or multiply the timestamp by 1000 when reading and writing the object respectively. There are other methods to achieve this result but this seems to be the more straight forward at the time.

You can find this concrete example in the /Datefest folder of the distribution.

About timestamps differences

Not every platform/operating system/framework treats datetime information the same way, specially when working with UNIX timestamps (PHP for Windows, for example cannot handle negative timestamps), therefore you will find that sometimes the information you send or receive is not always accurate. There are many things to consider when handling datetimes, such as daylight savings, timezones and formating issues.

Tests in the developing environment resulted in sometimes an hour of difference between the data sent and received, specially with Hessian Java.

Some of ealier tests also showed that Date/time information passing between Java and C# is also incorrect so this aspect will need to be addressed in the future to ensure full compatibility among platforms.

TODO: More examples and more testing

Edit - History - Print - Recent Changes - Search
Page last modified on January 01, 2006, at 06:52 AM

PmWiki can't process your request

Cannot acquire lockfile

We are sorry for any inconvenience.