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

Quando você tem um endereço IP e quer saber o nome de host por trás dele, a função gethostbyaddr() do PHP faz esse trabalho. Ela realiza uma consulta DNS reversa — o oposto de resolver um nome de domínio para um IP. Este artigo aborda sua sintaxe, valor de retorno, casos de uso comuns e as armadilhas que costumam pegar as pessoas de surpresa.

O que é a Função gethostbyaddr()?

A função gethostbyaddr() é uma função interna do PHP que realiza uma consulta DNS reversa (rDNS) para recuperar o nome de host registrado para um determinado endereço IP. Ela depende do resolvedor DNS do sistema, portanto o resultado depende da rede em que o script é executado e de o proprietário do IP ter configurado um registro PTR.

Fatos importantes para ter em mente:

• Ela aceita um endereço IPv4 ou IPv6 como string.
• Em caso de sucesso, retorna o nome de host como uma string.
• Em caso de falha na resolução, retorna a string do IP original sem alterações — não false. Esse é o principal comportamento surpreendente e determina como você deve verificar o resultado.
• Em caso de argumento inválido (uma string que não é um IP válido), retorna false e emite um aviso.

Uma consulta reversa só tem sucesso se o proprietário do bloco de IP tiver publicado um registro PTR. Muitos endereços (incluindo a maioria dos IPs residenciais e muitos IPs de nuvem) não possuem PTR ou possuem um que não corresponde ao registro direto, portanto um nome de host "ausente" é normal, e não um erro no seu código.

Sintaxe

gethostbyaddr(string $ip): string|false

Valor de retorno: o nome de host em caso de sucesso, a string $ip inalterada quando nenhum nome de host puder ser encontrado, ou false se $ip não for um endereço válido.

Exemplo Básico

Como a função retorna o próprio IP quando a resolução falha, você compara o resultado com a entrada para detectar a falha:

Aqui, 8.8.8.8 (Google Public DNS) resolve para um nome de host como dns.google. A verificação tripla distingue uma entrada inválida (false), um endereço não resolvido (retorna o IP) e uma consulta bem-sucedida.

Resolvendo o Nome de Host do Visitante

Um uso comum é em logs ou análises: converter o IP de um visitante em um nome de host legível.

<?php

$ip = $_SERVER['REMOTE_ADDR'] ?? '127.0.0.1';
$host = gethostbyaddr($ip);

echo $host === $ip
    ? "Visitor IP $ip has no reverse DNS entry."
    : "Visitor came from $host.";
?>

Não use o resultado para controle de acesso. O DNS reverso pode ser falsificado por quem controla o registro PTR do IP, portanto um nome de host como example.com não prova nada por si só. Para um DNS reverso confirmado pelo direto (FCrDNS confiável), consulte o nome de host com gethostbyaddr() e depois confirme se ele resolve de volta para o mesmo IP com gethostbyname().

Combinando com gethostbyname()

gethostbyaddr() e gethostbyname() são funções inversas. Você pode usá-las juntas para verificar se um nome de host e um IP realmente correspondem:

<?php

$ip = "8.8.8.8";
$host = gethostbyaddr($ip);
$confirmed = gethostbyname($host) === $ip;

echo "Host: $host\n";
echo "Forward-confirmed: " . ($confirmed ? "yes" : "no") . "\n";
?>

Quando $confirmed é yes, ambas as direções da consulta DNS concordam — o sinal mais forte que você obtém pelo DNS simples de que o nome de host é legítimo.

Armadilhas Comuns

• Um IP retornado não é um erro. Sempre verifique $result === $ip em vez de presumir que um resultado não-false é um nome de host.
• As consultas são lentas e bloqueantes. Cada chamada pode aguardar uma ida e volta pela rede. Evite chamá-la em um loop intenso a cada requisição; armazene os resultados em cache quando possível.
• Valide a entrada primeiro. Se o valor pode não ser um IP válido, passe-o por filter_var() com FILTER_VALIDATE_IP antes de chamar gethostbyaddr().
• Os resultados variam por ambiente. O mesmo IP pode retornar nomes de host diferentes (ou nenhum) dependendo dos servidores DNS configurados onde o script é executado.

Funções Relacionadas

• gethostbyname() — resolve um nome de host para um endereço IPv4 (a consulta direta).
• gethostbynamel() — obtém a lista completa de endereços IPv4 para um nome de host.
• gethostname() — obtém o nome de host da máquina local.
• checkdnsrr() — verifica se existem registros DNS de um determinado tipo para um host.
• ip2long() — converte um endereço IPv4 em sua representação inteira.

Conclusão

A função gethostbyaddr() realiza uma consulta DNS reversa, transformando um endereço IP em um nome de host. O detalhe crucial é o seu comportamento de retorno: ela devolve o IP original quando nenhum nome de host é encontrado e false apenas para entradas inválidas, portanto verifique o resultado com cuidado. Combine-a com gethostbyname() quando precisar de um DNS reverso confirmado pelo direto, e nunca confie em uma consulta reversa não verificada para decisões de segurança.

Prática