Date
[ class tree: Date ] [ index: Date ] [ all elements ]

Class: Date_TimeZone

Source Location: /Date-1.5.0a4/Date/TimeZone.php

Class Overview


TimeZone representation class, along with time zone information data


Author(s):

Version:

  • Release: 1.5.0a1

Copyright:

  • 1997-2007 Baba Buehler, Pierre-Alain Joye, C.A. Woodcock

Methods


Inherited Variables

Inherited Methods


Class Details

[line 76]
TimeZone representation class, along with time zone information data

The default timezone is set from the first valid timezone id found in one of the following places, in this order:

  • global $_DATE_TIMEZONE_DEFAULT
  • system environment variable PHP_TZ
  • system environment variable TZ
  • the result of date('T')
If no valid timezone id is found, the default timezone is set to 'UTC'. You may also manually set the default timezone by passing a valid id to Date_TimeZone::setDefault().

This class includes time zone data (from zoneinfo) in the form of a global array, $_DATE_TIMEZONE_DATA.



[ Top ]


Method Detail

Date_TimeZone (Constructor)   [line 318]

void Date_TimeZone( string $ps_id)

Constructor

If the supplied ID is invalid, the created time zone is "UTC".

A note about time zones of the form 'Etc/*' (quoted from the public domain 'tz' data-base (see ftp://elsie.nci.nih.gov/pub/ [file 'etcetera']):

These entries are mostly present for historical reasons, so that people in areas not otherwise covered by the tz files could use a time zone that was right for their area. These days, the tz files cover almost all the inhabited world, and the only practical need now for the entries that are not on UTC are for ships at sea that cannot use POSIX TZ settings.

  • Etc/GMT (GMT)
  • Etc/UTC (UTC)
  • Etc/UCT (UCT)
The following link uses older naming conventions, but it belongs here. We want this to work even on installations that omit the other older names.

  • Etc/GMT (equivalent to GMT)
  • Etc/UTC (equivalent to Etc/Universal)
  • Etc/UTC (equivalent to Etc/Zulu)
  • Etc/GMT (equivalent to Etc/Greenwich)
  • Etc/GMT (equivalent to Etc/GMT-0)
  • Etc/GMT (equivalent to Etc/GMT+0)
  • Etc/GMT (equivalent to Etc/GMT0)
We use POSIX-style signs in the Zone names and the output abbreviations, even though this is the opposite of what many people expect. POSIX has positive signs west of Greenwich, but many people expect positive signs east of Greenwich. For example, TZ='Etc/GMT+4' uses the abbreviation "GMT+4" and corresponds to 4 hours behind UTC (i.e. west of Greenwich) even though many people would expect it to mean 4 hours ahead of UTC (i.e. east of Greenwich).

In the draft 5 of POSIX 1003.1-200x, the angle bracket notation (which is not yet supported by the tz code) allows for TZ='<GMT-4>+4'; if you want time zone abbreviations conforming to ISO 8601 you can use TZ='<-0400>+4'. Thus the commonly-expected offset is kept within the angle bracket (and is used for display) while the POSIX sign is kept outside the angle bracket (and is used for calculation).

Do not use a TZ setting like TZ='GMT+4', which is four hours behind GMT but uses the completely misleading abbreviation "GMT".

Earlier incarnations of this package were not POSIX-compliant, and we did not want things to change quietly if someone accustomed to the old way uses the codes from previous versions so we moved the names into the Etc subdirectory.

  • Etc/GMT-14 (14 hours ahead of Greenwich)
  • Etc/GMT-13 (13)
  • Etc/GMT-12 (12)
  • Etc/GMT-11 (11)
  • Etc/GMT-10 (10)
  • Etc/GMT-9 (9)
  • Etc/GMT-8 (8)
  • Etc/GMT-7 (7)
  • Etc/GMT-6 (6)
  • Etc/GMT-5 (5)
  • Etc/GMT-4 (4)
  • Etc/GMT-3 (3)
  • Etc/GMT-2 (2)
  • Etc/GMT-1 (1)
  • Etc/GMT+1 (1 hour behind Greenwich)
  • Etc/GMT+2 (2)
  • Etc/GMT+3 (3)
  • Etc/GMT+4 (4)
  • Etc/GMT+5 (5)
  • Etc/GMT+6 (6)
  • Etc/GMT+7 (7)
  • Etc/GMT+8 (8)
  • Etc/GMT+9 (9)
  • Etc/GMT+10 (10)
  • Etc/GMT+11 (11)
  • Etc/GMT+12 (12)


Parameters:

string   $ps_id     the time zone ID

[ Top ]

getAvailableIDs   [line 1033]

array getAvailableIDs( )

Returns the list of valid time zone id strings
  • Return: an array of strings with the valid time zone IDs
  • Access: public

[ Top ]

getDefault   [line 417]

object Date_TimeZone getDefault( )

Returns a TimeZone object representing the system default time zone

The system default time zone is initialized during the loading of this file.

  • Return: object of the default time zone
  • Access: public

[ Top ]

getDSTLongName   [line 1151]

string getDSTLongName( )

Returns the DST long name for this time zone, e.g.

'Central Daylight Time'


[ Top ]

getDSTSavings   [line 935]

int getDSTSavings( )

Get the DST offset for this time zone

Returns the DST offset of this time zone, in milliseconds, if the zone observes DST, zero otherwise. If the offset is not known, the function returns one hour.

  • Return: the DST offset, in milliseconds or nought if the zone does not observe DST
  • Access: public

[ Top ]

getDSTShortName   [line 1167]

string getDSTShortName( )

Returns the DST short name for this time zone, e.g. 'CDT'

[ Top ]

getID   [line 1048]

string getID( )

Returns the time zone id for this time zone, e.g. "America/Chicago"
  • Return: the time zone ID
  • Access: public

[ Top ]

getLongName   [line 1078]

string getLongName( [mixed $pm_insummertime = false])

Returns the long name for this time zone

Long form of time zone name, e.g. 'Greenwich Mean Time'. Additionally a Date object can be passed in which case the Summer time name will be returned instead if the date falls in Summer time, e.g. 'British Summer Time', or a Boolean can be passed which explicitly specifies whether the date is in Summer time.

N.B. this is not a unique identifier - for this purpose use the time zone ID.


Parameters:

mixed   $pm_insummertime     a boolean specifying whether or not the date is in Summer time, or, a Date object to test for this condition

[ Top ]

getOffset   [line 1004]

int getOffset( mixed $pm_insummertime)

Returns the DST-corrected offset from UTC for the given date

Gets the offset to UTC for a given date/time, taking into account daylight savings time, if the time zone observes it and if it is in effect.

N.B. that the offset is calculated historically and in the future according to the current Summer time rules, and so this function is proleptically correct, but not necessarily historically correct. (Although if you want to be correct about times in the distant past, this class is probably not for you because the whole notion of time zones does not apply, and historically there are so many time zone changes, Summer time rule changes, name changes, calendar changes, that calculating this sort of information is beyond the scope of this package altogether.)


Parameters:

mixed   $pm_insummertime     a boolean specifying whether or not the date is in Summer time, or, a Date object to test for this condition

[ Top ]

getRawOffset   [line 969]

int getRawOffset( )

Returns the raw (non-DST-corrected) offset from UTC/GMT for this time zone

[ Top ]

getShortName   [line 1120]

string getShortName( [mixed $pm_insummertime = false])

Returns the short name for this time zone

Returns abbreviated form of time zone name, e.g. 'GMT'. Additionally a Date object can be passed in which case the Summer time name will be returned instead if the date falls in Summer time, e.g. 'BST'.

N.B. this is not a unique identifier - for this purpose use the time zone ID.


Parameters:

mixed   $pm_insummertime     a boolean specifying whether or not the date is in Summer time, or, a Date object to test for this condition

[ Top ]

getSummerTimeEndDay   [line 1288]

string getSummerTimeEndDay( )

Returns a code representing the day on which Summer time ends

Returns a string in one of the following forms:

  • 5 - the fifth of the month
  • lastSun - the last Sunday in the month
  • lastMon - the last Monday in the month
  • Sun>=8 - first Sunday on or after the 8th
  • Sun<=25 - last Sunday on or before the 25th


[ Top ]

getSummerTimeEndMonth   [line 1260]

int getSummerTimeEndMonth( )

Returns the month number in which Summer time ends

[ Top ]

getSummerTimeEndTime   [line 1307]

int getSummerTimeEndTime( )

Returns the time of day at which which Summer time ends

[ Top ]

getSummerTimeStartDay   [line 1214]

string getSummerTimeStartDay( )

Returns a code representing the day on which Summer time starts

Returns a string in one of the following forms:

  • 5 - the fifth of the month
  • lastSun - the last Sunday in the month
  • lastMon - the last Monday in the month
  • Sun>=8 - first Sunday on or after the 8th
  • Sun<=25 - last Sunday on or before the 25th


[ Top ]

getSummerTimeStartMonth   [line 1186]

int getSummerTimeStartMonth( )

Returns the month number in which Summer time starts

[ Top ]

getSummerTimeStartTime   [line 1241]

int getSummerTimeStartTime( )

Returns the time of day at which which Summer time starts

The returned time is an offset, in milliseconds, from midnight UTC. Note that the offset can be negative, which represents the fact that the time zone is East of Greenwich, and that when the clocks change locally, the time in Greenwich is actually a time belonging to the previous day in UTC. This, obviously, is unhelpful if you want to know the local time at which the clocks change, but it is of immense value for the purpose of calculation.


[ Top ]

hasDaylightTime   [line 603]

bool hasDaylightTime( )

Returns true if this zone observes daylight savings time
  • Return: true if this time zone has DST
  • Access: public

[ Top ]

inDaylightTime   [line 743]

bool inDaylightTime( object $pm_date, [bool $pb_repeatedhourdefault = false])

Returns whether the given date/time is in DST for this time zone

Works for all years, positive and negative. Possible problems are that when the clocks go forward, there is an invalid hour which is skipped. If a time in this hour is specified, this function returns an error. When the clocks go back, there is an hour which is repeated, that is, the hour is gone through twice - once in Summer time and once in standard time. If this time is specified, then this function returns '$pb_repeatedhourdefault', because there is no way of knowing which is correct, and both possibilities are equally likely.

Also bear in mind that the clocks go forward at the instant of the hour specified in the time-zone array below, and if this exact hour is specified then the clocks have actually changed, and this function reflects this.


Parameters:

object   $pm_date     Date object to test or array of day, month, year, seconds past midnight
bool   $pb_repeatedhourdefault     value to return if repeated hour is specified (defaults to false)

[ Top ]

inDaylightTimeStandard   [line 854]

bool inDaylightTimeStandard( object $pm_date)

Returns whether the given date/time in local standard time is in Summer time

For example, if the clocks go forward at 1.00 standard time, then if the specified date/time is at 1.00, the function will return true, although the correct local time will actually be 2.00.

This function is reliable for all dates and times, unlike the related function 'Date_TimeZone::inDaylightTime()', which will fail if passed an invalid time (the skipped hour) and will be wrong half the time if passed an ambiguous time (the repeated hour).

  • Return: true if this date is in Summer time for this time zone
  • See: Date_TimeZone::inDaylightTime()
  • Since: Method available since Release 1.5.0
  • Access: public

Parameters:

object   $pm_date     Date object to test or array of day, month, year, seconds past midnight

[ Top ]

isEqual   [line 527]

bool isEqual( object $tz)

Is this time zone equal to another

Tests to see if this time zone is equal (ids match) to a given Date_TimeZone object.


Parameters:

object   $tz     the Date_TimeZone object to test

[ Top ]

isEquivalent   [line 560]

bool isEquivalent( object $pm_tz)

Is this time zone equivalent to another

Tests to see if this time zone is equivalent to a given time zone object. Equivalence in this context consists in the two time zones having:

  • an equal offset from UTC in both standard and Summer time (if the time zones observe Summer time)
  • the same Summer time start and end rules, that is, the two time zones must switch from standard time to Summer time, and vice versa, on the same day and at the same time


Parameters:

object   $pm_tz     the Date_TimeZone object to test, or a valid time zone ID

[ Top ]

isValidID   [line 498]

bool isValidID( string $ps_id)

Tests if given time zone ID (e.g. 'London/Europe') is valid and unique

Checks if given ID is either represented in the $_DATE_TIMEZONE_DATA time zone data, or is a UTC offset in one of the following forms, i.e. an offset with no geographical or political base:

  • UTC[+/-][hh]:[mm] - e.g. UTC+03:00
  • UTC[+/-][hh][mm] - e.g. UTC-0530
  • UTC[+/-][hh] - e.g. UTC+03
  • UTC[+/-][h] - e.g. UTC-1
(the last is not an ISO 8601 standard but is the preferred form)

N.B. these are not sanctioned by any ISO standard, but the form of the offset itself, i.e. the part after the characters 'UTC', is the ISO 8601 standard form for representing this part.

The form '[+/-][h]' is not ISO conformant, but ISO 8601 only defines the form of the time zone offset of a particular time, that is, it actually defines the form '<time>UTC[+/-][hh]', and its purview does not apparently cover the name of the time zone itself. For this there is no official international standard (or even a non- international standard). The closest thing to a sanctioning body is the 'tz' database (http://www.twinsun.com/tz/tz-link.htm) which is run by volunteers but which is heavily relied upon by various programming languages and the internet community. However they mainly define geographical/political time zone names of the form 'London/Europe' because their main aim is to collate the time zone definitions which are set by individual countries/states, not to prescribe any standard.

However it seems that the de facto standard to describe time zones as non-geographically/politically-based areas where the local time on all clocks reads the same seems to be the form 'UTC[+/-][h]' for integral numbers of hours, and 'UTC[+/-][hh]:[mm]' otherwise. (See http://en.wikipedia.org/wiki/List_of_time_zones)

N.B. 'GMT' is also commonly used instead of 'UTC', but 'UTC' seems to be technically preferred. GMT-based IDs still exist in the 'tz data-base', but beware of POSIX-style offsets which are the opposite way round to what people normally expect.


Parameters:

string   $ps_id     the time zone ID to test

[ Top ]

setDefault   [line 434]

void setDefault( string $id)

Sets the system default time zone to the time zone in $id
  • Access: public

Parameters:

string   $id     the time zone id to use

[ Top ]


Documentation generated on Tue, 08 Oct 2013 05:30:31 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.