Signatur
Beschreibung
gethostbyname() führt eine DNS-Auflösung für den übergebenen Hostnamen durch und gibt die zugehörige IPv4-Adresse als Zeichenkette in der Notation a.b.c.d zurück. Die Funktion nutzt den systemseitigen Resolver und ist damit abhängig von der DNS-Konfiguration des Servers.
Kann der Hostname nicht aufgelöst werden, gibt die Funktion den ursprünglichen Hostnamen unverändert zurück — nicht false. Dies ist ein häufiger Fallstrick: Ein Fehler muss durch einen expliziten Vergleich des Rückgabewerts mit dem Eingabewert erkannt werden.
Die Funktion liefert nur eine einzige IPv4-Adresse, auch wenn für den Hostnamen mehrere A-Records existieren. Für vollständige DNS-Abfragen (mehrere Adressen, IPv6, andere Record-Typen) sollte stattdessen dns_get_record() oder gethostbynamel() verwendet werden.
Typische Einsatzgebiete sind Validierungen, Logging oder einfache Netzwerkchecks, bei denen die IP-Adresse eines Hostnamens bekannt sein muss, etwa beim Aufbau von Verbindungen oder der Überprüfung von Remote-Adressen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $hostname Pflicht | string | Der aufzulösende Hostname, z. B. www.example.com. Wird eine IP-Adresse übergeben, wird diese direkt zurückgegeben. |
Rückgabewert
93.184.216.34). Kann der Hostname nicht aufgelöst werden, wird der ursprüngliche Hostname unverändert zurückgegeben — es gibt keinen false-Rückgabewert.Beispiele
Hostnamen in IPv4-Adresse auflösen
<?php
$host = 'www.example.com';
$ip = gethostbyname($host);
if ($ip === $host) {
echo "DNS-Auflösung fehlgeschlagen für: $host";
} else {
echo "IP-Adresse von $host: $ip";
}
Überprüfung, ob ein Remote-Host bekannt ist
<?php
function resolveHost(string $hostname): ?string {
$ip = gethostbyname($hostname);
// Fehlschlag erkennen: Rückgabe == Eingabe
return ($ip !== $hostname) ? $ip : null;
}
$hosts = ['www.php.net', 'nicht-vorhanden.invalid'];
foreach ($hosts as $host) {
$result = resolveHost($host);
if ($result !== null) {
echo "$host => $result\n";
} else {
echo "$host => nicht auflösbar\n";
}
}
// Wichtig · Fallstricke
Wichtiger Fallstrick: Im Fehlerfall gibt gethostbyname() den übergebenen Hostnamen zurück, nicht false. Der Fehler muss daher immer durch $ip === $hostname erkannt werden.
Nur IPv4: Die Funktion unterstützt ausschließlich IPv4-Adressen (A-Records). Für IPv6 (AAAA-Records) muss dns_get_record() mit dem Typ DNS_AAAA genutzt werden.
Sicherheit: Übergeben Sie niemals vom Benutzer kontrollierte Hostnamen ohne vorherige Validierung, da dies für SSRF-Angriffe (Server-Side Request Forgery) missbraucht werden kann, falls die aufgelöste IP für weitergehende Netzwerkanfragen verwendet wird.
Performance: Die Funktion ist blockierend und kann bei langsamen oder nicht erreichbaren DNS-Servern zu Timeouts führen. In kritischen Anwendungen empfiehlt sich ein Timeout-Mechanismus oder ein asynchroner DNS-Resolver.