Função PHP gethostbyname(): Tudo o Que Você Precisa Saber

Quando o seu código precisa saber onde um servidor realmente está na rede — para fazer ping, conectar um socket, registrar o endereço resolvido ou adicioná-lo a uma lista de permissões — você começa com um nome de host como example.com e consulta o DNS pelo IP. A função gethostbyname() do PHP faz exatamente isso: dado um nome de host, ela retorna o endereço IPv4 correspondente como uma string.

Este capítulo aborda o que a função retorna, o problema que pega a maioria dos desenvolvedores de surpresa (como ela sinaliza falha) e os padrões com os quais você realmente a utiliza.

Sintaxe

gethostbyname(string $hostname): string

Ela recebe um único parâmetro:

• $hostname — o nome de host a resolver, por exemplo "www.example.com".

A função realiza uma consulta DNS (uma consulta de registro A) e retorna o primeiro endereço IPv4 encontrado, formatado como uma string de quatro octetos separados por pontos, como "93.184.216.34".

gethostbyname() resolve apenas IPv4 (registros A). Não há equivalente para IPv6 nesta família de funções — para registros AAAA, use dns_get_record() com o tipo DNS_AAAA.

Exemplo básico

A função realiza uma consulta DNS em "example.com" e imprime uma linha como:

The IP address for host name example.com is 93.184.216.34

O IP exato pode mudar ao longo do tempo e pode variar por região, pois é obtido do DNS em tempo real.

O problema da falha: ela retorna o nome de host sem alterações

Este é o detalhe mais importante. gethostbyname() não retorna false nem lança uma exceção em caso de falha. Quando a consulta falha — o nome não existe ou o DNS está inacessível — ela retorna a string $hostname que você passou, sem alterações.

Por isso, você não pode simplesmente verificar if ($ip). Você precisa verificar se o resultado realmente parece um endereço 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";
}

Uma verificação mais robusta é validar o resultado com filter_var(), o que funciona mesmo no caso raro em que o próprio nome de host se parece com um 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";
}

Obtendo todos os endereços com gethostbynamel()

gethostbyname() retorna apenas um endereço, mesmo quando um nome de host mapeia para vários IPs (comum em serviços com balanceamento de carga). Para obter a lista completa, use a função irmã gethostbynamel(), que retorna um array com todos os endereços IPv4:

<?php

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

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

Observe que gethostbynamel() retorna false em caso de falha, ao contrário de gethostbyname().

A direção inversa

Se você já tem um endereço IP e quer o nome de host associado a ele, use a função inversa, gethostbyaddr():

<?php

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

Quando usá-la

• Resolver um nome de host configurado para um IP antes de abrir uma conexão de socket de baixo nível.
• Registrar o endereço resolvido junto às requisições para auditoria ou limitação de taxa.
• Verificações rápidas de conectividade ou sanidade de DNS em scripts e sondas de saúde.

Para trabalhos de DNS mais completos — servidores de e-mail, todos os tipos de registro, TTLs — use dns_get_record(), checkdnsrr() ou dns_get_mx().

Conclusão

gethostbyname() converte um nome de host em um único endereço IPv4 com uma linha de código. Lembre-se da sua peculiaridade: em caso de falha, ela devolve o nome de host em vez de retornar false, por isso sempre valide o resultado antes de confiar nele. Quando precisar de todos os endereços, use gethostbynamel(); para ir de um IP de volta ao nome, use gethostbyaddr().

Prática