Funzione PHP gethostbyname(): Tutto Quello che Devi Sapere

Quando il tuo codice ha bisogno di sapere dove si trova fisicamente un server nella rete — per eseguire un ping, aprire una connessione socket, registrare l'indirizzo risolto o inserirlo in una whitelist — parti da un nome host come example.com e chiedi al DNS il suo IP. La funzione gethostbyname() di PHP fa esattamente questo: dato un nome host, restituisce il corrispondente indirizzo IPv4 come string.

Questo capitolo illustra cosa restituisce la funzione, la trappola in cui cadono la maggior parte degli sviluppatori (come segnala il fallimento) e i pattern con cui la si usa concretamente.

Sintassi

gethostbyname(string $hostname): string

Accetta un singolo parametro:

• $hostname — il nome host da risolvere, ad esempio "www.example.com".

La funzione esegue una ricerca DNS (una query di tipo A) e restituisce il primo indirizzo IPv4 trovato, formattato come string in notazione decimale puntata, ad esempio "93.184.216.34".

gethostbyname() risolve solo record IPv4 (A) . Non esiste un equivalente IPv6 in questa famiglia di funzioni — per i record AAAA usa dns_get_record() con il tipo DNS_AAAA.

Esempio di base

La funzione esegue una ricerca DNS su "example.com" e stampa una riga simile a:

The IP address for host name example.com is 93.184.216.34

L'indirizzo IP esatto può cambiare nel tempo e può variare in base alla regione, poiché proviene dal DNS in tempo reale.

La trappola del fallimento: restituisce il nome host invariato

Questo è il dettaglio più importante. gethostbyname() non restituisce false né lancia un'eccezione in caso di errore. Quando la risoluzione fallisce — il nome non esiste o il DNS non è raggiungibile — restituisce la string $hostname che hai passato, invariata.

Quindi non puoi semplicemente verificare if ($ip). Devi controllare se il risultato ha effettivamente l'aspetto di un indirizzo 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";
}

Un controllo più robusto consiste nel validare il risultato con filter_var(), che funziona anche nel raro caso in cui il nome host stesso abbia l'aspetto di un indirizzo 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";
}

Ottenere tutti gli indirizzi con gethostbynamel()

gethostbyname() restituisce solo un indirizzo, anche quando un nome host è mappato a più IP (comune nei servizi con bilanciamento del carico). Per ottenere l'elenco completo, usa la funzione gemella gethostbynamel(), che restituisce un array di tutti gli indirizzi IPv4:

<?php

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

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

Nota che gethostbynamel() restituisce false in caso di errore, a differenza di gethostbyname().

La direzione inversa

Se hai già un indirizzo IP e vuoi risalire al nome host corrispondente, usa la funzione inversa gethostbyaddr():

<?php

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

Quando usarla

• Per risolvere un nome host configurato in un indirizzo IP prima di aprire una connessione socket di basso livello.
• Per registrare l'indirizzo risolto insieme alle richieste a fini di audit o rate-limiting.
• Per controlli rapidi di connettività o di correttezza del DNS in script e health probe.

Per operazioni DNS più articolate — server di posta, tutti i tipi di record, TTL — utilizza invece dns_get_record(), checkdnsrr() o dns_get_mx().

Conclusione

gethostbyname() converte un nome host in un singolo indirizzo IPv4 con una riga di codice. Ricorda la sua particolarità: in caso di fallimento restituisce il nome host anziché false, quindi valida sempre il risultato prima di utilizzarlo. Quando hai bisogno di tutti gli indirizzi, passa a gethostbynamel(); per risalire da un IP a un nome, usa gethostbyaddr().

Esercitazione