Fonction PHP gethostname() : Tout ce que vous devez savoir

La fonction PHP gethostname() retourne le nom d'hôte de la machine qui exécute actuellement votre script PHP — le même nom que vous obtiendriez avec la commande hostname dans un terminal. Elle est pratique pour journaliser quel serveur a traité une requête, créer des clés de cache par hôte, ou afficher des informations de diagnostic dans un panneau d'administration. Cette page couvre sa syntaxe, ce qu'elle retourne (y compris en cas d'échec), des cas d'utilisation concrets, les pièges courants, et son rapport avec les autres fonctions de recherche d'hôte.

Syntaxe

gethostname() ne prend aucun paramètre :

gethostname(): string|false

Elle retourne une string contenant le nom d'hôte en cas de succès, ou false en cas d'échec. La fonction a été introduite dans PHP 5.3 et remplace l'ancienne php_uname('n').

Le nom d'hôte est le nom de la machine, et non la valeur de l'en-tête HTTP Host:. Sur un serveur web, gethostname() retourne le nom du serveur (par exemple web-01), tandis que le domaine saisi par le visiteur se trouve dans $_SERVER['HTTP_HOST'].

Exemple de base

Le script demande au système d'exploitation le nom de la machine locale et l'affiche. La sortie exacte dépend de l'endroit où le code s'exécute — il peut s'agir de quelque chose comme web-01, localhost, ou un identifiant de conteneur tel que a1b2c3d4e5f6.

Gérer les échecs en toute sécurité

Étant donné que gethostname() peut retourner false, vérifiez le résultat avant de l'utiliser plutôt que de supposer que vous obtenez toujours une string. Utilisez l'opérateur strict === pour qu'une string vide ne soit pas confondue avec un échec :

<?php

$hostname = gethostname();

if ($hostname === false) {
    echo "Could not determine the host name.";
} else {
    echo "Running on: $hostname";
}

Quand l'utiliser ?

• Journalisation et diagnostics — étiquetez chaque ligne de journal avec le serveur qui l'a produite, ce qui est précieux derrière un équilibreur de charge où plusieurs machines servent le même site.
• Clés de cache ou de verrou par hôte — préfixez les fichiers temporaires ou les entrées de cache pour éviter les conflits entre deux serveurs.
• Pages de santé et de statut — montrez aux opérateurs sur quel nœud ils se trouvent.
• Jobs distribués — enregistrez quel worker a pris en charge une tâche en file d'attente.

gethostname() par rapport aux fonctions associées

gethostname() répond uniquement à la question « quel est le nom de cette machine ? ». Pour rechercher d'autres hôtes sur le réseau, PHP propose des fonctions séparées :

• gethostbyname() — résoudre un nom d'hôte en adresse IPv4.
• gethostbyaddr() — résolution inverse d'une adresse IP en nom d'hôte.
• gethostbynamel() — obtenir la liste complète des adresses IPv4 pour un nom d'hôte.

Une suite courante consiste à les combiner — obtenir le nom local, puis le résoudre en IP :

<?php

$hostname = gethostname();
$ip = $hostname !== false ? gethostbyname($hostname) : 'unknown';

echo "Host: $hostname, resolved IP: $ip";

Pièges courants

• Ce n'est pas le domaine du client. N'utilisez pas gethostname() pour détecter le site/domaine sur lequel une requête est arrivée ; lisez plutôt $_SERVER['HTTP_HOST'].
• La valeur peut être inattendue dans les conteneurs. Dans Docker, le nom d'hôte est généralement l'identifiant (généré aléatoirement) du conteneur, et non le nom convivial de votre serveur.
• Gérez toujours false. Un système mal configuré peut ne pas réussir à rapporter un nom d'hôte ; protégez-vous contre cela comme indiqué ci-dessus.

Conclusion

gethostname() est une petite fonction sans paramètre qui retourne le nom de la machine exécutant votre script, ou false en cas d'échec. Utilisez-la pour la journalisation, les diagnostics et les clés par hôte — et utilisez gethostbyname(), gethostbyaddr() ou gethostbynamel() lorsque vous avez besoin de rechercher d'autres hôtes sur le réseau.

Pratique