dev.ImpactClub.ro

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{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**:
<code>
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
</code>
...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 =====
<code>

              +------------+                 |
              |  DATETIME  |                 | MAIN CLASS
              +------------+                 |
                    |                        |
       +------------+------------+           |
       |                         |           |
  +----------+                   |           |
  | TIMEZONE |                   |           | CURRENT STANDARD TZ
  +----------+              +---------+      |
                            | DATEDST |      | CHECK DST DATE
                            +---------+      |
</code>

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**
<code php>
  $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
</code>

**Properties**
<code php>
  $timestamp                   // unix timestamp in seconds (GMT)
  $timezone                    // TIMEZONE object
  $datedst                     // DATEDST object
</code>     

**Methods**
<code php>
  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)
</code>     

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**
<code php> 
  $region                      // current region
  $stdzone                     // standard time
  $dstzone                     // daylight saving time
</code>
     
**Methods**
<code php>
  TIMEZONE($tz)                 // class constructor
                                //   - tz=NULL      -> GMT
                                //   - tz=string    -> string tz
  setZone($zone)                // sets standard and dts timezones
                                //   - zone = {'stdzone', 'dstzone'}
</code>

==== 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**
<code php> 
  $type                        // DST type
  $date                        // DATE object (recursion)
</code>
     
**Methods**
<code php>
  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
</code>

===== Query-by-exemple  =====
**current GMT time**
<code php>    
$date=new DATETIME();
echo $date->getTime();
</code>

**custom GMT time**
<code php>
$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
</code>       

**custom local time to GMT**
<code php>
$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
</code>

**custom local time (no DST) to GMT**
<code php>
$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
</code>

**custom local time (DST set) to GMT**
<code php>
$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
</code>

**current local time in America/New_York**
<code php>
$date=new DATETIME(null,'America/New_York');
echo $date->getTime();
</code>       

**custom GMT time to local time in Europe/Berlin**
<code php>
$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
</code>       

**custom local time to local time in Europe/Berlin**
<code php>
$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
</code>

**change current timezone**
<code php>
$date->setTZ('Europe/Bucharest');
echo $date->getTime();                               // Friday, 05th of August 2005 01:10:10 AM EEST
</code>

**custom string time to local time in Australia/Sydney**
<code php>
$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
</code>       

**date manipulation**
<code php>
$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
</code>       

**advanced date manipulation**
<code php>
$time="last Sunday";                                 
$date->setTime($time);                               
echo $date->getTime();                               // Sunday, 10th of September 2000 07:00:00 AM AEST
</code>       

**custom date format**
<code php>
$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
</code>

===== 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
dev.ImpactClub.ro

User Tools

Site Tools

Page Tools
