Class: Date_TimeZone

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:

array getAvailableIDs( )

Returns the list of valid time zone id strings

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.

string getDSTLongName( )

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

'Central Daylight Time'

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.

string getDSTShortName( )

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

string getID( )

Returns the time zone id for this time zone, e.g. "America/Chicago"

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:

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:

int getRawOffset( )

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

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:

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

int getSummerTimeEndMonth( )

Returns the month number in which Summer time ends

int getSummerTimeEndTime( )

Returns the time of day at which which Summer time ends

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

int getSummerTimeStartMonth( )

Returns the month number in which Summer time starts

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.

bool hasDaylightTime( )

Returns true if this zone observes daylight savings time

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:

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).

Parameters:

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:

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:

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:

void setDefault( string $id)

Sets the system default time zone to the time zone in $id

Parameters: