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

Como desenvolvedor PHP, pode ser necessário obter todos os endereços IP associados a um determinado nome de host, não apenas um. Um único domínio frequentemente resolve para múltiplos endereços IP por motivos de balanceamento de carga ou redundância. A função built-in gethostbynamel() lida com isso: ela realiza uma consulta DNS e retorna um array com todos os endereços IPv4 associados a esse nome de host.

Esta página explica o que gethostbynamel() retorna, como ela difere da singular gethostbyname(), como tratar falhas com segurança e quando utilizá-la.

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

A função gethostbynamel() é uma função built-in do PHP que recupera uma lista de endereços IPv4 correspondentes a um determinado nome de host na Internet. O l no final do nome significa list (lista) — ela é a irmã que retorna um array de gethostbyname(), a qual retorna apenas um único endereço como string.

Internamente, ela realiza uma consulta DNS de registro A. Um site de grande porte como google.com pode publicar vários registros A, portanto gethostbynamel() permite ver todos eles, e não apenas o primeiro.

Somente IPv4. gethostbynamel() retorna exclusivamente endereços IPv4 (registro A). Ela não retorna endereços IPv6 (registro AAAA). Para inspecionar IPv6 ou outros tipos de registro, use dns_get_record().

Como Usar a Função gethostbynamel()

Usar a função gethostbynamel() é simples. Veja a sintaxe:

Sintaxe PHP da Função gethostbynamel()

gethostbynamel(string $hostname): array|false

A função aceita um parâmetro:

• $hostname: O nome de host para o qual deseja recuperar todos os endereços IPv4 (por exemplo, "www.example.com").

Valor de Retorno

Retorna um array indexado numericamente de strings de endereços IPv4 em caso de sucesso, ou false se o nome de host não puder ser resolvido.

Veja um exemplo de como usar a função gethostbynamel() para recuperar todos os endereços IP associados a um nome de host:

Como Usar a Função gethostbynamel()

Neste exemplo, recuperamos todos os endereços IPv4 associados ao nome de host "example.com". A função realiza uma consulta DNS e retorna um array de endereços. Em seguida, percorremos o array e exibimos cada um. Observe a comparação estrita !== false: isso é importante porque um array vazio é "falso" em contexto booleano, mas uma consulta com falha retorna o boolean false, portanto verificar explicitamente por false é o teste seguro e inequívoco.

Saída Esperada

IP address for host name example.com is 93.184.216.34

Os endereços exatos que você vê dependem dos registros DNS atuais e da sua rede, portanto podem diferir da saída acima.

gethostbynamel() vs gethostbyname()

Essas duas funções são fáceis de confundir. A diferença está no que elas retornam:

Um padrão comum é contar quantos endereços um host anuncia:

<?php

$hostname = "example.com";
$addresses = gethostbynamel($hostname);

if ($addresses === false) {
    echo "Could not resolve $hostname\n";
} else {
    echo $hostname . " resolves to " . count($addresses) . " IPv4 address(es):\n";
    echo implode(", ", $addresses) . "\n";
}

Saída Esperada

example.com resolves to 1 IPv4 address(es):
93.184.216.34

Quando Usar gethostbynamel()

• Detectar hosts com múltiplos endereços. Quando um domínio é servido por vários servidores (DNS round-robin, uma CDN), gethostbynamel() revela o conjunto completo de endereços.
• Listas de permissões / regras de firewall. Resolva um host para todos os seus IPs antes de criar uma lista de permissões, para não deixar passar nenhum dos backends.
• Diagnósticos e monitoramento. Exiba todos os endereços para os quais um nome resolve ao solucionar problemas de conectividade.

Se você precisa de suporte a IPv6 ou outros tipos de registro DNS (MX, TXT, CNAME), use dns_get_record() ou checkdnsrr().

Conclusão

A função gethostbynamel() recupera a lista completa de endereços IPv4 associados a um determinado nome de host, ao contrário de gethostbyname(), que retorna apenas um. Compreendendo seu comportamento exclusivo de IPv4, seu valor de retorno false em caso de falha e o tratamento adequado de erros, você pode integrá-la com segurança em suas aplicações PHP para consultas DNS, diagnósticos e listas de permissões.

Prática