PHP 8.4: Intl: New intltz_get_iana_id
function and IntlTimeZone::getCanonicalID
method
The Intl extension in PHP 8.4 provides a new function named intltz_get_iana_id
and a new static method IntlTimeZone::getIanaID()
in the IntlTimeZone
class that returns the IANA time zone ID for a given timezone identifier.
In most situations, the return value is the same as the passed timezone identifier. However, in situations where a given timezone identifier is deprecated, or otherwise has a superseded timezone identifier, the new function/method help canonicalize the timezone identifier.
For example, the timezone for Cyprus, Asia/Nicosia
, is sometimes used as Europe/Nicosia
. The new intltz_get_iana_id
function and IntlTimeZone::getIanaID()
method provide an easy way to lookup these inconsistencies and to retrieve the correct IANA identifier for the timezone.
See IANA tzdata/backward for a list of affected timezone identifiers.
This function is available only if the Intl extension is compiled with ICU version 74 or later. See ICU-22452 for the change in the upstream ICU package.
intltz_get_iana_id('Europe/Berlin'); // Valid, returns the same
// "Europe/Berlin"
IntlTimeZone::getIanaID('America/New_York'); // Valid, returns the same
// "America/New_York"
intltz_get_iana_id('Mars'); // Invalid, returns false
// false
intltz_get_iana_id('Europe/Nicosia'); // Returns as Asia/Nicosia
// "Asia/Nicosia"
IntlTimeZone::getIanaID('Asia/Chongqing'); // Duplicating existing location
// "Asia/Shanghai"
intltz_get_iana_id
function synopsis
/**
* Get the IANA identifier from a given timezone
* @param string $timezoneId
* @return string|false
*/
function intltz_get_iana_id(string $timezoneId): string|false {}
intltz_get_iana_id
is declared in the global namespace.- Passing an invalid timezone ID returns
false
. - See also:
intltz_get_canonical_id
that is similar, but returns system-canonical timezone ID, which overlaps (but not entirely) with the IANA timezone list.
IntlTimeZone::getIanaID()
class IntlTimeZone {
// ...
/**
* Get the IANA identifier from a given timezone
* @param string $timezoneId
* @return string|false
*/
public static function getIanaID(string $timezoneId): string|false {}
// ...
}
- The new
getIanaID
method is astatic
method. - Alias to
intltz_get_iana_id
function. - Passing an invalid timezone ID returns
false
. - See also:
IntlTimeZone::getCanonicalID
that is similar, but returns system-canonical timezone ID, which overlaps (but not entirely) with the IANA timezone list.
Backward Compatibility Impact
The new intltz_get_iana_id
function is declared in the global namespace, and unless a PHP application declares a function with an identical name, this should not cause any backward compatibility issues.
PHP Classes that extend IntlTimeZone
without implementing an incompatible getIanaID
method will not experience any backward compatibility issues either.
The IANA timezone identifier data comes from the ICU library. It is possible to polyfill the intltz_get_iana_id
function with user-land PHP by hardcoding the timezone identifiers that need to be "canonicalized". However, this can be unreliable and requires additional maintenance to keep this list current.