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 a static 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.

---

intltz_get_iana_id Implementation