idn_to_ascii — Funktion · PHP-Referenz

Signatur

idn_to_ascii(string $domain, int $flags = IDNA_DEFAULT, int $variant = INTL_IDNA_VARIANT_UTS46, array &$idna_info = []): string|false

Beschreibung

idn_to_ascii() wandelt einen Domainnamen, der Unicode-Zeichen (z. B. Umlaute oder andere nicht-ASCII-Zeichen) enthält, in die standardisierte ASCII-kompatible Kodierung (ACE) gemäß dem IDNA-Standard (Internationalized Domain Names in Applications) um. Das Ergebnis beginnt üblicherweise mit dem Präfix xn-- und kann von jedem DNS-System verarbeitet werden.

Die Funktion ist besonders nützlich, wenn Formulareingaben mit internationalisierten Domains (z. B. münchen.de) für HTTP-Anfragen, E-Mail-Adressen oder DNS-Abfragen vorbereitet werden müssen, da diese Systeme nur ASCII-Zeichen verarbeiten können.

Der Parameter $variant sollte auf INTL_IDNA_VARIANT_UTS46 gesetzt werden, da INTL_IDNA_VARIANT_2003 seit PHP 7.2 als veraltet gilt und in PHP 8.0 entfernt wurde. Mit dem optionalen Parameter $idna_info erhält man zusätzliche Diagnoseinformationen über die Konvertierung, darunter den resultierenden Namen, etwaige Fehler und den Unicode-Status.

Die Funktion ist Teil der intl-Erweiterung und erfordert, dass diese in PHP aktiviert ist. Ohne intl-Erweiterung steht sie nicht zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$domain Pflicht	string		Der zu konvertierende Domainname als UTF-8-codierter String, z. B. `münchen.de`.
$flags	int	IDNA_DEFAULT	Optionale Flags zur Steuerung des Konvertierungsverhaltens. Mögliche Konstanten sind z. B. `IDNA_ALLOW_UNASSIGNED`, `IDNA_USE_STD3_RULES`, `IDNA_CHECK_BIDI`, `IDNA_CHECK_CONTEXTJ`, `IDNA_NONTRANSITIONAL_TO_ASCII`.
$variant	int	INTL_IDNA_VARIANT_UTS46	Der zu verwendende IDNA-Standard. Empfohlen wird `INTL_IDNA_VARIANT_UTS46`. `INTL_IDNA_VARIANT_2003` ist seit PHP 7.2 veraltet und wurde in PHP 8.0 entfernt.
$idna_info	array	[]	Wird mit Diagnoseinformationen zur Konvertierung befüllt: `result` (konvertierter Name), `isTransitionalDifferent` (bool) und `errors` (Bitmaske mit aufgetretenen Fehlern).

Rückgabewert

Typ

string|false

Beschreibung

Gibt den konvertierten ASCII-Domainnamen als String zurück oder false bei einem Fehler, z. B. bei einem ungültigen Domainnamen.

Beispiele

Einfache Konvertierung eines deutschen Domainnamens

<?php
$domain = 'münchen.de';
$ascii = idn_to_ascii($domain, IDNA_DEFAULT, INTL_IDNA_VARIANT_UTS46);
echo $ascii;
// Ausgabe: xn--mnchen-3ya.de

xn--mnchen-3ya.de

Konvertierung mit Diagnoseinformationen via $idna_info

<?php
$domain = 'faß.example';
$idnaInfo = [];
$ascii = idn_to_ascii($domain, IDNA_DEFAULT, INTL_IDNA_VARIANT_UTS46, $idnaInfo);

if ($ascii !== false) {
    echo 'ASCII-Domain: ' . $ascii . PHP_EOL;
} else {
    echo 'Konvertierung fehlgeschlagen.' . PHP_EOL;
}

print_r($idnaInfo);

ASCII-Domain: xn--fa-hia.example Array ( [result] => xn--fa-hia.example [isTransitionalDifferent] => 1 [errors] => 0 )

Praxisbeispiel: Domain vor einer HTTP-Anfrage normalisieren

<?php
function normalisiereDomainfuerHttp(string $url): string {
    $parsed = parse_url($url);
    if (!isset($parsed['host'])) {
        return $url;
    }
    $asciiHost = idn_to_ascii($parsed['host'], IDNA_DEFAULT, INTL_IDNA_VARIANT_UTS46);
    if ($asciiHost === false) {
        throw new \InvalidArgumentException('Ungültiger Domainname: ' . $parsed['host']);
    }
    return str_replace($parsed['host'], $asciiHost, $url);
}

echo normalisiereDomainfuerHttp('https://münchen.de/pfad?q=test');
// Ausgabe: https://xn--mnchen-3ya.de/pfad?q=test

https://xn--mnchen-3ya.de/pfad?q=test

// Wichtig · Fallstricke

Veralteter Variant: Der früher übliche Aufruf ohne $variant-Argument oder mit INTL_IDNA_VARIANT_2003 ist seit PHP 7.2 veraltet und funktioniert ab PHP 8.0 nicht mehr. Immer INTL_IDNA_VARIANT_UTS46 verwenden.

Abhängigkeit von intl: Die Funktion ist nur verfügbar, wenn die PHP-Erweiterung intl installiert und aktiviert ist. Bei fehlendem intl-Modul wird ein fataler Fehler ausgelöst.

Rückgabewert prüfen: Da die Funktion bei einem ungültigen Domainnamen false zurückgibt, sollte der Rückgabewert stets mit === false geprüft werden, bevor der Wert weiterverwendet wird.

Umkehrfunktion: Mit idn_to_utf8() lässt sich ein Punycode-Domainname wieder in die Unicode-Darstellung zurückkonvertieren.

Siehe auch

idn_to_utf8 parse_url INTL_IDNA_VARIANT_UTS46