intltz_get_canonical_id — Funktion · PHP-Referenz

Signatur

intltz_get_canonical_id(string $timezoneId, bool &$isSystemID = null): string|false

Beschreibung

intltz_get_canonical_id() ist eine prozedurale Variante der Methode IntlTimeZone::getCanonicalID() und normalisiert eine beliebige Zeitzonen-ID auf ihre kanonische Form gemäß dem ICU-Standard. Dies ist nützlich, wenn man sicherstellen möchte, dass veraltete oder alternative Zeitzonen-Bezeichner (z. B. Aliasnamen) auf ihren offiziellen, kanonischen Bezeichner zurückgeführt werden.

Der optionale zweite Parameter $isSystemID wird als Referenz übergeben und nach dem Aufruf auf true gesetzt, wenn die ursprüngliche ID bereits eine System-Zeitzonen-ID war, oder auf false, wenn es sich um einen Alias handelte. Dies ermöglicht es, gelieferte Zeitzonen-Angaben auf ihre Herkunft hin zu klassifizieren.

Typische Einsatzbereiche sind die Normalisierung von Benutzereingaben für Zeitzonen, die Validierung von Zeitzonen-IDs vor der Speicherung in einer Datenbank sowie die Übersetzung veralteter Bezeichner (wie US/Eastern) auf den modernen äquivalenten Bezeichner (z. B. America/New_York).

Die Funktion gibt false zurück, wenn die übergebene ID unbekannt oder ungültig ist, sodass eine einfache Fehlerprüfung möglich ist.

Parameter

Name	Typ	Default	Beschreibung
$timezoneId Pflicht	string		Die zu normalisierende Zeitzonen-ID, z. B. `'US/Eastern'`, `'Europe/Berlin'` oder ein ICU-Alias.
$isSystemID	bool	null	Wird nach dem Aufruf auf `true` gesetzt, wenn die übergebene ID eine System-Zeitzonen-ID ist, andernfalls auf `false`. Wird als Referenz übergeben.

Rückgabewert

Typ

string|false

Beschreibung

Gibt die kanonische Zeitzonen-ID als Zeichenkette zurück. Wenn die übergebene ID ungültig oder unbekannt ist, wird false zurückgegeben.

Beispiele

Veraltete Zeitzonen-ID normalisieren

<?php
// Normalisierung eines veralteten Zeitzonen-Aliases
$canonical = intltz_get_canonical_id('US/Eastern', $isSystemID);

if ($canonical !== false) {
    echo "Kanonische ID: " . $canonical . PHP_EOL;
    echo "Ist System-ID: " . ($isSystemID ? 'ja' : 'nein') . PHP_EOL;
} else {
    echo "Ungültige Zeitzonen-ID" . PHP_EOL;
}

Kanonische ID: America/New_York Ist System-ID: nein

Validierung und Normalisierung von Benutzereingaben

<?php
// Zeitzonen-Eingaben aus einem Formular normalisieren und validieren
$userInputs = ['Europe/Berlin', 'CET', 'Ungueltig/Zone', 'UTC'];

foreach ($userInputs as $input) {
    $canonical = intltz_get_canonical_id($input, $isSystemID);
    if ($canonical !== false) {
        echo sprintf(
            "'%s' => '%s' (System-ID: %s)\n",
            $input,
            $canonical,
            $isSystemID ? 'ja' : 'nein'
        );
    } else {
        echo "'$input' ist keine gültige Zeitzonen-ID.\n";
    }
}

'Europe/Berlin' => 'Europe/Berlin' (System-ID: ja) 'CET' => 'CET' (System-ID: nein) 'Ungueltig/Zone' ist keine gültige Zeitzonen-ID. 'UTC' => 'UTC' (System-ID: ja)

// Wichtig · Fallstricke

ICU-Version: Das Ergebnis dieser Funktion kann je nach installierter ICU-Bibliotheksversion leicht variieren, da ICU die Zeitzonen-Daten regelmäßig aktualisiert. Es empfiehlt sich, die ICU-Version auf dem Produktionssystem aktuell zu halten.

Erweiterung: Die Funktion ist Bestandteil der intl-Erweiterung, die in der php.ini aktiviert sein muss (extension=intl). Fehlt die Erweiterung, wird ein fataler Fehler ausgelöst.

OOP-Äquivalent: Alternativ kann die statische Methode IntlTimeZone::getCanonicalID($timezoneId, $isSystemID) verwendet werden, die identisch funktioniert.

Siehe auch

IntlTimeZone::getCanonicalID intltz_create_time_zone intltz_get_id intltz_get_equivalent_id timezone_name_from_abbr