{{keywords>php class package time date timezone daylight saving offset}}
====== ImpactClub Datetime 1.0 beta ======
{{php:datetime.jpg }} DATETIME 1.0 beta is a package designed to work in PHP 4.x or 5.x. It can be used freely by anyone in personal or business application, in non commercial way. It represents a general way to timezone abstraction and standardization.
===== Download =====
* 1.0 beta (20/12/2005) -- {{php:datetime.1.0b.zip|}}
* 1.0 RC -- available soon
===== Features =====
**1.0b december 2005**
* It is very fast
* It does not store records about specific DST dates in the future
* Uses a efficient algorithm to get DST
* It can calculate valid dates for any year starting 1970
* Very easy to implement in any software project.
* Designed to work in any PHP website
* Works in any operation system (Windows/Linux/Macos)
* It does not use operating system calls, thus it is safe.
===== Description =====
World time zones do not fallow a standard and countries adopted time zones without obeying a rule. The easiest examples are: IRAN (GMT+3:30), INDIA (GMT+5:30), CENTRAL AUSTRALIA (GMT+9:30) and many more.
The problem is more difficult when DST (Daylight Saving Time) must be calculated as there are several regions in the world with several types of algorithms.
**Examples**:
Region DST Begins DST Ends
North America First Sunday in April Last Sunday in October
Europe Last Sunday in March Last Sunday in October
Australia Last Sunday in October Last Sunday in March
New Zealand First Sunday in October Third Sunday in March
Brazil First Sunday in October First Sunday in February
...And the lists can continue.
Fist Sunday in April it is not on the same day every year (3 April 2005, 2 April 2006, 1 April 2007, 6 April 2008, 5April 2009, 4 April 2010. and so on.)
Thus it is very hard to calculate WHAT time is it in WEST AUSTRALIA if in EAST US is 4:30pm 25th December 2005? First you must apply time zone differences (GMT-5 -> GMT+10). Then you must observe the DST (In US is 0-winter, and in Australia is 1 - summer) But what if you have to find more than 1 time zone? What time is in Europe/Bucharest, Europe/Berlin, Africa/South Africa, Asia/Japan.?
There are lots of software packages to help you do that, but all of them store all the DST data in files or in database, witch is somehow limited.
They store DST start and end dates for the next 5 years.
The DATATIME package uses a efficient algorithm to calculate DST data.
===== General structure =====
+------------+ |
| DATETIME | | MAIN CLASS
+------------+ |
| |
+------------+------------+ |
| | |
+----------+ | |
| TIMEZONE | | | CURRENT STANDARD TZ
+----------+ +---------+ |
| DATEDST | | CHECK DST DATE
+---------+ |
In your websites you should use only instances to DATATIME class. In this HIGH LEVEL of abstraction you wont wary about the way date queries are sent to server, setting correct timezones and testing for DST.
The DATETIME class uses 2 subclasses to do all of that. TIMEZONE class sets time zone offsets and description to be used in data manipulation
DATEDST check for a valid DST date in zones like US, Europe and Australia.
===== Configuration =====
Generally DATETIME package does need any configuration.
You may change the $TIMEZONE global variable to update timezone formats if someone decides to change the standards over time.
===== Package Help =====
==== DATETIME (main class) ====
**Global Variables**
$TIMEZZONE // array, timezone standards
$TIMEZONES['region'] // array, timezone regions an properties
// - standard zone
// - daylight saving time zone
// - dst algorithm key
$TIMEZONES['offset'] // array, GMT offsets in seconds
$TIMEZONES['standard'] // array, timezone codes
**Properties**
$timestamp // unix timestamp in seconds (GMT)
$timezone // TIMEZONE object
$datedst // DATEDST object
**Methods**
DATETIME(time, tz) // class constructor
// - time=NULL -> current GMT time
// - time=INTEGER -> timestamp
// - time=STRING -> strtotime conversion
// - tz=NULL -> GMT
// - tz=string -> string tz
setTime($time) // sets local or GMT time
getTime($format, $tz) // returns formated time in TZ
getGMT() // returns timestamp in GMT
getLocal() // returns timestamp in current TZ
getLocalStd() // returns timestamp in current TZ (no DST)
setTZ(tz) // sets new timezone
getTZ() // gets TZ short name
getTZStd() // gets TZ short name (no DST)
getTZName() // gets TZ long name
getTZNameStd() // gets TZ long name (no DST)
getOffset() // get TZ offset
getOffsetStd() // get TZ offset (no DST)
getType() // get TZ time
getTypeStd() // get TZ time (no DST)
NOTE: It is recommended not to direct access object's properties. You can use all available functions with correct parameters.
==== TIMEZONE (subclass) ====
NOTE: Do not direct access any of object's properties or methods. You can use main class (DATETIME) functions. This object is medium level and you can access it's contents only if you need a more sophisticated approach on timezone.
**Properties**
$region // current region
$stdzone // standard time
$dstzone // daylight saving time
**Methods**
TIMEZONE($tz) // class constructor
// - tz=NULL -> GMT
// - tz=string -> string tz
setZone($zone) // sets standard and dts timezones
// - zone = {'stdzone', 'dstzone'}
==== DATEDST (subclass) ====
NOTE: Do not direct access any of object's properties or methods. You can use main class (DATETIME) functions. This object is medium level and you can access it's contents only if you need a more sophisticated approach on DST.
**Properties**
$type // DST type
$date // DATE object (recursion)
**Methods**
DATEDST(date) // class constructor, date=DATE object
isDST(time) // returns 1 if time is in DST
isDST_eu(time) // DST in Europe
isDST_us(time) // DST in United States
isDST_au(time) // DST in Australia
===== Query-by-exemple =====
**current GMT time**
$date=new DATETIME();
echo $date->getTime();
**custom GMT time**
$time=gmmktime(1,10,15,8,5,2005); // 05/08/2005 1:10:15 GMT
$date=new DATETIME($time);
echo $date->getTime(); // Friday, 05th of August 2005 01:10:15 AM UTC
**custom local time to GMT**
$time=mktime(1,10,10,8,5,2005); // 05/08/2005 1:10:15 local
$date=new DATETIME($time);
echo $date->getTime(); // Thursday, 04th of August 2005 10:10:10 PM UTC
**custom local time (no DST) to GMT**
$time=mktime(1,10,10,8,5,2005,0); // 05/08/2005 1:10:15 local (no DST)
$date=new DATETIME($time);
echo $date->getTime(); // Thursday, 04th of August 2005 11:10:10 PM UTC
**custom local time (DST set) to GMT**
$time=mktime(1,10,10,8,5,2005,1); // 05/08/2005 1:10:15 local (DST set)
$date=new DATETIME($time);
echo $date->getTime(); // Thursday, 04th of August 2005 10:10:10 PM UTC
**current local time in America/New_York**
$date=new DATETIME(null,'America/New_York');
echo $date->getTime();
**custom GMT time to local time in Europe/Berlin**
$time=gmmktime(1,10,10,8,5,2005); // 05/08/2005 1:10:15 GMT
$date=new DATETIME($time,'Europe/Berlin');
echo $date->getTime(); // Friday, 05th of August 2005 03:10:10 AM CEST
**custom local time to local time in Europe/Berlin**
$time=mktime(1,10,10,8,5,2005); // 05/08/2005 1:10:15 local
$date=new DATETIME($time,'Europe/Berlin');
echo $date->getTime(); // Friday, 05th of August 2005 12:10:10 AM CEST
**change current timezone**
$date->setTZ('Europe/Bucharest');
echo $date->getTime(); // Friday, 05th of August 2005 01:10:10 AM EEST
**custom string time to local time in Australia/Sydney**
$time="10 September 2000 23:15 CET"; // 10/09/2000 23:15:00 CET
$date=new DATETIME($time,'Australia/Sydney');
echo $date->getTime(); // Monday, 11th of September 2000 08:15:00 AM AEST
**date manipulation**
$time="+1 week -2 days -1 hour -40 seconds"; // use format in GNU manual page titled "Date Input Formats"
$date->setTime($time); // http://www.gnu.org/software/tar/manual/html_chapter/tar_7.html
echo $date->getTime(); // Saturday, 16th of September 2000 07:14:20 AM AEST
**advanced date manipulation**
$time="last Sunday";
$date->setTime($time);
echo $date->getTime(); // Sunday, 10th of September 2000 07:00:00 AM AEST
**custom date format**
$format="D M j G:i:s T Y"; // use PHP's date() format
echo $date->getTime($format); // Sun Sep 10 7:00:00 AEST 2000
===== ToDO =====
* add all regions to $TIMEZONE global
* add more date manipulation function
* move $TIMEZZONE global in database
* use database functions to get timezones
* date format internationalization
* date builder class