Función PHP gethostbyname(): Todo lo que necesitas saber

Cuando tu código necesita saber dónde vive realmente un servidor en la red — para hacer ping, conectar un socket, registrar la dirección resuelta o incluirla en una lista blanca — partes de un nombre de host como example.com y consultas el DNS para obtener su IP. La función gethostbyname() de PHP hace exactamente eso: dado un nombre de host, devuelve la dirección IPv4 correspondiente como string.

Este capítulo cubre qué devuelve la función, el problema que confunde a la mayoría de los desarrolladores (cómo indica un fallo) y los patrones con los que realmente se usa.

Sintaxis

gethostbyname(string $hostname): string

Acepta un único parámetro:

• $hostname — el nombre de host a resolver, por ejemplo "www.example.com".

La función realiza una búsqueda DNS (una consulta de registro A) y devuelve la primera dirección IPv4 que encuentra, en formato de cadena separada por puntos, como "93.184.216.34".

gethostbyname() resuelve solo IPv4 (registros A). No existe un equivalente para IPv6 en esta familia de funciones — para registros AAAA usa dns_get_record() con el tipo DNS_AAAA.

Ejemplo básico

La función realiza una búsqueda DNS en "example.com" e imprime una línea similar a:

The IP address for host name example.com is 93.184.216.34

La IP exacta puede cambiar con el tiempo y variar según la región, ya que proviene del DNS en tiempo real.

El problema con los fallos: devuelve el nombre de host sin cambios

Este es el detalle más importante. gethostbyname() no devuelve false ni lanza excepciones en caso de fallo. Cuando la búsqueda falla — el nombre no existe o el DNS no es accesible — devuelve el string $hostname que pasaste, sin modificar.

Por eso no puedes simplemente comprobar if ($ip). Debes verificar si el resultado realmente parece una dirección IP:

<?php

$hostname = "this-host-does-not-exist.invalid";
$ip = gethostbyname($hostname);

if ($ip === $hostname) {
    echo "Could not resolve $hostname";
} else {
    echo "Resolved $hostname to $ip";
}

Una comprobación más robusta es validar el resultado con filter_var(), que funciona incluso en el raro caso en que el nombre de host en sí parezca una IP:

<?php

$hostname = "example.com";
$ip = gethostbyname($hostname);

if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
    echo "Resolved to a valid IPv4 address: $ip";
} else {
    echo "Resolution failed for $hostname";
}

Obtener todas las direcciones con gethostbynamel()

gethostbyname() devuelve solo una dirección, incluso cuando un nombre de host apunta a varias IPs (habitual en servicios con balanceo de carga). Para obtener la lista completa, usa la función hermana gethostbynamel(), que devuelve un array con todas las direcciones IPv4:

<?php

$ips = gethostbynamel("example.com");

if ($ips === false) {
    echo "Lookup failed.";
} else {
    foreach ($ips as $ip) {
        echo $ip . PHP_EOL;
    }
}

Ten en cuenta que gethostbynamel() devuelve false en caso de fallo, a diferencia de gethostbyname().

La dirección inversa

Si ya tienes una dirección IP y quieres el nombre de host asociado, usa la función inversa gethostbyaddr():

<?php

$host = gethostbyaddr("93.184.216.34");
echo $host;

Cuándo usarla

• Resolver un nombre de host configurado a una IP antes de abrir una conexión de socket de bajo nivel.
• Registrar la dirección resuelta junto a las solicitudes para auditoría o limitación de velocidad.
• Comprobaciones rápidas de conectividad o de DNS en scripts y sondas de salud.

Para tareas DNS más complejas — servidores de correo, todos los tipos de registros, TTLs — usa dns_get_record(), checkdnsrr() o dns_get_mx().

Conclusión

gethostbyname() convierte un nombre de host en una única dirección IPv4 con una sola línea de código. Recuerda su particularidad: en caso de fallo, te devuelve el nombre de host en lugar de retornar false, así que siempre valida el resultado antes de confiar en él. Cuando necesites todas las direcciones, usa gethostbynamel(); para ir de una IP de vuelta a un nombre, usa gethostbyaddr().

Práctica