## Creating a timezone form item using Date API

This is simple. Just use the 'date_timezone' type, which is provided by date_api.module.

    <?php
      $form['timezone'] = array(
        '#type' => 'date_timezone',
        '#default_value' => $timezone,
        '#description' => "Select a timezone if all the events will happen in the same place. Select that place's timezone",
      );
    ?>

## Converting to and from UTC

In the new system you just need to know the timezone name and either the UTC or local time. We store the UTC time and the timezone name in the database (in two separate fields). We retrieve that data and do:

    <?php
    $date = the UTC value from the database
    $local_zone = the name of the local timezone
    $type = the type of date value, DATE_DATETIME, DATE_ISO, or DATE_UNIX

    $date = date_make_date($date, 'UTC', $type);
    date_timezone_set($date, timezone_open($local_zone);

    $date now contains the local value of the date.
    Output it like:

    print date_format_date($date, 'custom', 'm/d/Y H:i');
    ?>

To convert a local date back to UTC to store it in the database, do:

    <?php
    $date = local date value
    $local_zone = the name of the local timezone
    $type = the type of date value, DATE_DATETIME, DATE_ISO, or DATE_UNIX

    $date = date_make_date($date, $local_zone, $type);
    date_timezone_set($date, timezone_open('UTC');

    $date now contains the UTC value of the date.
    Output it like:

    print date_format_date($date, 'custom', 'm/d/Y H:i');
    ?>

## Use of timezone abbreviations

The API doesn't handle timezone abbreviations at all, there's no way to do it right because they are not unique (EST could be Eastern Standard Time or European Summer Time). We need the full, undeprecated timezone name, which looks like 'America/Chicago'. It is comprised of the name of the continent and the major city in the timezone. Older names like 'US/Central' are deprecated because the area names change, but city names rarely do. Some good info about timezones is at http://en.wikipedia.org/wiki/Zoneinfo.

Also, we do not use spaces in the timezone names, so we use America/New_York, not America/New York. The PHP 5.2 date functions and MYSQL native timezone handling all expect names without spaces in them to work correctly.

You can use the php function `timezone_name_from_abbr()` to try to translate to and from abbreviations, but it's not entirely reliable, as noted above. If we have the current offset and we know if it's currently daylight savings time or not, you can combine that with the abbreviation to get the timezone name, but that's a lot of 'if's.

## Timezone Names

The complete list of allowed, undeprecated timezone names is:

    Africa/Algiers
    Africa/Asmera
    Africa/Bangui
    Africa/Blantyre
    Africa/Brazzaville
    Africa/Bujumbura
    Africa/Cairo
    Africa/Ceuta
    Africa/Dar_es_Salaam
    Africa/Djibouti
    Africa/Douala
    Africa/Gaborone
    Africa/Harare
    Africa/Johannesburg
    Africa/Kampala
    Africa/Khartoum
    Africa/Kigali
    Africa/Kinshasa
    Africa/Lagos
    Africa/Libreville
    Africa/Luanda
    Africa/Lubumbashi
    Africa/Lusaka
    Africa/Malabo
    Africa/Maputo
    Africa/Maseru
    Africa/Mbabane
    Africa/Mogadishu
    Africa/Nairobi
    Africa/Ndjamena
    Africa/Niamey
    Africa/Porto-Novo
    Africa/Tripoli
    Africa/Tunis
    Africa/Windhoek
    America/Adak
    America/Anchorage
    America/Anguilla
    America/Antigua
    America/Araguaina
    America/Aruba
    America/Asuncion
    America/Atka
    America/Barbados
    America/Belem
    America/Belize
    America/Boa_Vista
    America/Bogota
    America/Boise
    America/Buenos_Aires
    America/Cambridge_Bay
    America/Cancun
    America/Caracas
    America/Catamarca
    America/Cayenne
    America/Cayman
    America/Chicago
    America/Chihuahua
    America/Cordoba
    America/Costa_Rica
    America/Cuiaba
    America/Curacao
    America/Dawson
    America/Dawson_Creek
    America/Denver
    America/Detroit
    America/Dominica
    America/Edmonton
    America/Eirunepe
    America/El_Salvador
    America/Ensenada
    America/Fort_Wayne
    America/Fortaleza
    America/Glace_Bay
    America/Godthab
    America/Goose_Bay
    America/Grand_Turk
    America/Grenada
    America/Guadeloupe
    America/Guatemala
    America/Guayaquil
    America/Guyana
    America/Halifax
    America/Havana
    America/Hermosillo
    America/Indiana/Indianapolis
    America/Indiana/Knox
    America/Indiana/Marengo
    America/Indiana/Vevay
    America/Indianapolis
    America/Inuvik
    America/Iqaluit
    America/Jamaica
    America/Jujuy
    America/Juneau
    America/Kentucky/Louisville
    America/Kentucky/Monticello
    America/Knox_IN
    America/La_Paz
    America/Lima
    America/Los_Angeles
    America/Louisville
    America/Maceio
    America/Managua
    America/Manaus
    America/Martinique
    America/Mazatlan
    America/Mendoza
    America/Menominee
    America/Merida
    America/Mexico_City
    America/Miquelon
    America/Monterrey
    America/Montevideo
    America/Montreal
    America/Montserrat
    America/Nassau
    America/New_York
    America/Nipigon
    America/Nome
    America/Noronha
    America/Panama
    America/Pangnirtung
    America/Paramaribo
    America/Phoenix
    America/Port-au-Prince
    America/Port_of_Spain
    America/Porto_Acre
    America/Porto_Velho
    America/Puerto_Rico
    America/Rainy_River
    America/Rankin_Inlet
    America/Recife
    America/Regina
    America/Rio_Branco
    America/Rosario
    America/Santiago
    America/Santo_Domingo
    America/Sao_Paulo
    America/Scoresbysund
    America/Shiprock
    America/St_Johns
    America/St_Kitts
    America/St_Lucia
    America/St_Thomas
    America/St_Vincent
    America/Swift_Current
    America/Tegucigalpa
    America/Thule
    America/Thunder_Bay
    America/Tijuana
    America/Tortola
    America/Vancouver
    America/Virgin
    America/Whitehorse
    America/Winnipeg
    America/Yakutat
    America/Yellowknife
    Antarctica/Casey
    Antarctica/Davis
    Antarctica/DumontDUrville
    Antarctica/Mawson
    Antarctica/McMurdo
    Antarctica/Palmer
    Antarctica/South_Pole
    Antarctica/Syowa
    Antarctica/Vostok
    Arctic/Longyearbyen
    Asia/Aden
    Asia/Almaty
    Asia/Amman
    Asia/Anadyr
    Asia/Aqtau
    Asia/Aqtobe
    Asia/Ashgabat
    Asia/Ashkhabad
    Asia/Baghdad
    Asia/Bahrain
    Asia/Baku
    Asia/Bangkok
    Asia/Beirut
    Asia/Bishkek
    Asia/Brunei
    Asia/Calcutta
    Asia/Chungking
    Asia/Colombo
    Asia/Dacca
    Asia/Damascus
    Asia/Dhaka
    Asia/Dili
    Asia/Dubai
    Asia/Dushanbe
    Asia/Gaza
    Asia/Harbin
    Asia/Hong_Kong
    Asia/Hovd
    Asia/Irkutsk
    Asia/Istanbul
    Asia/Jakarta
    Asia/Jayapura
    Asia/Jerusalem
    Asia/Kabul
    Asia/Kamchatka
    Asia/Karachi
    Asia/Kashgar
    Asia/Katmandu
    Asia/Krasnoyarsk
    Asia/Kuala_Lumpur
    Asia/Kuching
    Asia/Kuwait
    Asia/Macao
    Asia/Magadan
    Asia/Manila
    Asia/Muscat
    Asia/Nicosia
    Asia/Novosibirsk
    Asia/Omsk
    Asia/Phnom_Penh
    Asia/Pyongyang
    Asia/Qatar
    Asia/Rangoon
    Asia/Riyadh
    Asia/Riyadh87
    Asia/Riyadh88
    Asia/Riyadh89
    Asia/Saigon
    Asia/Samarkand
    Asia/Seoul
    Asia/Shanghai
    Asia/Singapore
    Asia/Taipei
    Asia/Tashkent
    Asia/Tbilisi
    Asia/Tehran
    Asia/Tel_Aviv
    Asia/Thimbu
    Asia/Thimphu
    Asia/Tokyo
    Asia/Ujung_Pandang
    Asia/Ulaanbaatar
    Asia/Ulan_Bator
    Asia/Urumqi
    Asia/Vientiane
    Asia/Vladivostok
    Asia/Yakutsk
    Asia/Yekaterinburg
    Asia/Yerevan
    Atlantic/Azores
    Atlantic/Bermuda
    Atlantic/Canary
    Atlantic/Cape_Verde
    Atlantic/Faeroe
    Atlantic/Jan_Mayen
    Atlantic/Madeira
    Atlantic/South_Georgia
    Atlantic/Stanley
    Australia/ACT
    Australia/Adelaide
    Australia/Brisbane
    Australia/Broken_Hill
    Australia/Canberra
    Australia/Darwin
    Australia/Hobart
    Australia/LHI
    Australia/Lindeman
    Australia/Lord_Howe
    Australia/Melbourne
    Australia/NSW
    Australia/North
    Australia/Perth
    Australia/Queensland
    Australia/South
    Australia/Sydney
    Australia/Tasmania
    Australia/Victoria
    Australia/West
    Australia/Yancowinna
    Europe/Amsterdam
    Europe/Andorra
    Europe/Athens
    Europe/Belfast
    Europe/Belgrade
    Europe/Berlin
    Europe/Bratislava
    Europe/Brussels
    Europe/Bucharest
    Europe/Budapest
    Europe/Chisinau
    Europe/Copenhagen
    Europe/Dublin
    Europe/Gibraltar
    Europe/Helsinki
    Europe/Istanbul
    Europe/Kaliningrad
    Europe/Kiev
    Europe/Lisbon
    Europe/Ljubljana
    Europe/London
    Europe/Luxembourg
    Europe/Madrid
    Europe/Malta
    Europe/Minsk
    Europe/Monaco
    Europe/Moscow
    Europe/Nicosia
    Europe/Oslo
    Europe/Paris
    Europe/Prague
    Europe/Riga
    Europe/Rome
    Europe/Samara
    Europe/San_Marino
    Europe/Sarajevo
    Europe/Simferopol
    Europe/Skopje
    Europe/Sofia
    Europe/Stockholm
    Europe/Tallinn
    Europe/Tirane
    Europe/Tiraspol
    Europe/Uzhgorod
    Europe/Vaduz
    Europe/Vatican
    Europe/Vienna
    Europe/Vilnius
    Europe/Warsaw
    Europe/Zagreb
    Europe/Zaporozhye
    Europe/Zurich
    Indian/Antananarivo
    Indian/Chagos
    Indian/Christmas
    Indian/Cocos
    Indian/Comoro
    Indian/Kerguelen
    Indian/Mahe
    Indian/Maldives
    Indian/Mauritius
    Indian/Mayotte
    Indian/Reunion
    Pacific/Apia
    Pacific/Auckland
    Pacific/Chatham
    Pacific/Easter
    Pacific/Efate
    Pacific/Enderbury
    Pacific/Fakaofo
    Pacific/Fiji
    Pacific/Funafuti
    Pacific/Galapagos
    Pacific/Gambier
    Pacific/Guadalcanal
    Pacific/Guam
    Pacific/Honolulu
    Pacific/Johnston
    Pacific/Kiritimati
    Pacific/Kosrae
    Pacific/Kwajalein
    Pacific/Majuro
    Pacific/Marquesas
    Pacific/Midway
    Pacific/Nauru
    Pacific/Niue
    Pacific/Norfolk
    Pacific/Noumea
    Pacific/Pago_Pago
    Pacific/Palau
    Pacific/Pitcairn
    Pacific/Ponape
    Pacific/Port_Moresby
    Pacific/Rarotonga
    Pacific/Saipan
    Pacific/Samoa
    Pacific/Tahiti
    Pacific/Tarawa
    Pacific/Tongatapu
    Pacific/Truk
    Pacific/Wake
    Pacific/Wallis
    Pacific/Yap
    Pacific/French_Polynesia-Marquesas_Islands
    UTC