intltz_get_equivalent_id — Funktion · PHP-Referenz

Signatur

intltz_get_equivalent_id(string $zoneId, int $index, bool $canonicalID = false, string $region = ''): string|false

Beschreibung

intltz_get_equivalent_id() ist die prozedurale Variante von IntlTimeZone::getEquivalentID() und liefert eine bestimmte ID aus der Gruppe von Zeitzonen-IDs, die zur angegebenen ID äquivalent sind. Äquivalente Zeitzonen sind solche, die denselben UTC-Offset und dieselben Übergänge (z. B. Sommerzeit) teilen.

Über den Parameter $index kann eine bestimmte äquivalente ID aus der Gruppe abgerufen werden. Die Gesamtzahl der äquivalenten IDs lässt sich zuvor mit intltz_count_equivalent_ids() ermitteln, sodass man die Gruppe vollständig iterieren kann.

Wenn $canonicalID auf true gesetzt ist, werden nur kanonische Zeitzonen-IDs berücksichtigt. Der optionale Parameter $region schränkt die Suche auf Äquivalente einer bestimmten Region (z. B. 'DE') ein, was besonders nützlich ist, wenn man länderspezifische Zeitzonen sucht.

Typische Einsatzgebiete sind Kalender-Anwendungen, Benutzerprofile mit Zeitzonenwahl sowie jede Anwendung, die Zeitzonen-Synonyme oder -Aliase verwalten oder darstellen muss.

Parameter

Name	Typ	Default	Beschreibung
$zoneId Pflicht	string		Die Zeitzonen-ID, deren Äquivalenzgruppe durchsucht wird, z. B. `'Europe/Berlin'`.
$index Pflicht	int		Der nullbasierte Index der gewünschten äquivalenten ID innerhalb der Äquivalenzgruppe. Gültige Werte liegen zwischen `0` und `intltz_count_equivalent_ids($zoneId) - 1`.
$canonicalID	bool	false	Wenn `true`, werden nur kanonische Zeitzonen-IDs in der Äquivalenzgruppe berücksichtigt.
$region	string		Ein optionaler zweistelliger ISO-3166-Ländercode (z. B. `'DE'`), um die Äquivalenzgruppe auf Zeitzonen einer bestimmten Region einzuschränken.

Rückgabewert

Typ

string|false

Beschreibung

Gibt die Zeitzonen-ID als string zurück, oder false, wenn der Index außerhalb des gültigen Bereichs liegt oder kein passendes Äquivalent gefunden werden konnte.

Beispiele

Alle äquivalenten IDs zu einer Zeitzone ausgeben

<?php
$zoneId = 'Europe/Berlin';
$count = intltz_count_equivalent_ids($zoneId);

echo "Äquivalente IDs für '{$zoneId}' ({$count} gesamt):\n";
for ($i = 0; $i < $count; $i++) {
    $equiv = intltz_get_equivalent_id($zoneId, $i);
    echo "  [{$i}] {$equiv}\n";
}

Äquivalente IDs für 'Europe/Berlin' (3 gesamt): [0] Europe/Berlin [1] Europe/Budapest [2] Europe/Sarajevo

Nur kanonische äquivalente IDs abrufen

<?php
$zoneId = 'US/Eastern';
$count = intltz_count_equivalent_ids($zoneId);

echo "Kanonische Äquivalente für '{$zoneId}':\n";
for ($i = 0; $i < $count; $i++) {
    $equiv = intltz_get_equivalent_id($zoneId, $i, true);
    if ($equiv !== false) {
        echo "  [{$i}] {$equiv}\n";
    }
}

// Ungültiger Index — gibt false zurück
$result = intltz_get_equivalent_id($zoneId, 9999);
var_dump($result);

Kanonische Äquivalente für 'US/Eastern': [0] America/New_York bool(false)

// Wichtig · Fallstricke

Hinweis zur Indexierung: Der Index ist nullbasiert. Ein Index außerhalb des gültigen Bereichs (kleiner 0 oder größer/gleich der Anzahl der Äquivalente) führt zur Rückgabe von false. Daher sollte der Rückgabewert stets geprüft werden (=== false).

Abhängigkeit: Diese Funktion benötigt die ICU-Bibliothek (International Components for Unicode). Verhalten und Ergebnisse können je nach installierter ICU-Version variieren. Prüfe ggf. INTL_ICU_VERSION, wenn Kompatibilität über verschiedene Umgebungen hinweg wichtig ist.

Objektorientierte Alternative: Statt der prozeduralen Form kann auch IntlTimeZone::getEquivalentID(string $zoneId, int $index) verwendet werden, was in modernem PHP-Code bevorzugt wird.

Siehe auch

intltz_count_equivalent_ids intltz_get_canonical_id intltz_create_time_zone IntlTimeZone