Fonction PHP gethostbyname() : tout ce que vous devez savoir

Lorsque votre code doit savoir où un serveur se trouve réellement sur le réseau — pour lui envoyer un ping, ouvrir une connexion socket, enregistrer l'adresse résolue ou la placer en liste blanche — vous partez d'un nom d'hôte comme example.com et interrogez le DNS pour obtenir son IP. La fonction PHP gethostbyname() fait exactement cela : à partir d'un nom d'hôte, elle retourne l'adresse IPv4 correspondante sous forme de string.

Ce chapitre explique ce que la fonction retourne, le piège qui surprend la plupart des développeurs (la façon dont elle signale un échec), ainsi que les patterns que vous utilisez réellement avec elle.

Syntaxe

gethostbyname(string $hostname): string

Elle prend un seul paramètre :

• $hostname — le nom d'hôte à résoudre, par exemple "www.example.com".

La fonction effectue une résolution DNS (une requête d'enregistrement A) et retourne la première adresse IPv4 trouvée, formatée sous forme de string en notation pointée, comme "93.184.216.34".

gethostbyname() résout uniquement les enregistrements IPv4 (A) . Il n'existe pas d'équivalent IPv6 dans cette famille de fonctions — pour les enregistrements AAAA, utilisez dns_get_record() avec le type DNS_AAAA.

Exemple de base

La fonction effectue une résolution DNS sur "example.com" et affiche une ligne telle que :

The IP address for host name example.com is 93.184.216.34

L'adresse IP exacte peut changer au fil du temps et varier selon la région, car elle provient du DNS en direct.

Le piège en cas d'échec : la fonction retourne le nom d'hôte inchangé

C'est le détail le plus important. gethostbyname() ne retourne pas false et ne lève pas d'exception en cas d'échec. Lorsque la résolution échoue — le nom n'existe pas ou le DNS est inaccessible — elle retourne la string $hostname que vous avez transmise, inchangée.

Vous ne pouvez donc pas vous contenter de vérifier if ($ip). Vous devez vérifier si le résultat ressemble réellement à une adresse 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";
}

Une vérification plus robuste consiste à valider le résultat avec filter_var(), ce qui fonctionne même dans le rare cas où le nom d'hôte lui-même ressemble à une adresse 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";
}

Obtenir toutes les adresses avec gethostbynamel()

gethostbyname() ne retourne qu'une seule adresse, même lorsqu'un nom d'hôte correspond à plusieurs IP (courant pour les services en équilibrage de charge). Pour obtenir la liste complète, utilisez la fonction associée gethostbynamel(), qui retourne un array de toutes les adresses IPv4 :

<?php

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

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

Notez que gethostbynamel() retourne false en cas d'échec, contrairement à gethostbyname().

La direction inverse

Si vous disposez déjà d'une adresse IP et souhaitez obtenir le nom d'hôte associé, utilisez la fonction inverse gethostbyaddr() :

<?php

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

Quand l'utiliser

• Résoudre un nom d'hôte configuré en adresse IP avant d'ouvrir une connexion socket de bas niveau.
• Enregistrer l'adresse résolue aux côtés des requêtes à des fins d'audit ou de limitation de débit.
• Effectuer des vérifications rapides de connectivité ou de cohérence DNS dans des scripts et des sondes de santé.

Pour des travaux DNS plus avancés — serveurs de messagerie, tous les types d'enregistrements, TTL — utilisez plutôt dns_get_record(), checkdnsrr() ou dns_get_mx().

Conclusion

gethostbyname() convertit un nom d'hôte en une seule adresse IPv4 en une ligne de code. N'oubliez pas sa particularité : en cas d'échec, elle vous retourne le nom d'hôte plutôt que false, donc validez toujours le résultat avant de lui faire confiance. Lorsque vous avez besoin de toutes les adresses, passez à gethostbynamel() ; pour aller d'une IP à un nom, utilisez gethostbyaddr().

Pratique