Differences

This shows you the differences between two versions of the page.

--- php:datetime [2008/04/29 12:46]
+++ php:datetime [2008/04/29 12:46] (current)
@@ Line 1: / Line 1: @@
+{{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

Differences

Page Tools