Funzione PHP gethostname(): Tutto quello che devi sapere

La funzione PHP gethostname() restituisce il nome host della macchina che sta eseguendo il tuo script PHP — lo stesso nome che vedresti con il comando hostname nel terminale. È utile per registrare quale server ha gestito una richiesta, per costruire chiavi di cache per host specifici, o per mostrare informazioni diagnostiche in un pannello di amministrazione. Questa pagina ne descrive la sintassi, cosa restituisce (anche in caso di errore), casi d'uso realistici, insidie comuni e il rapporto con altre funzioni di ricerca host.

Sintassi

gethostname() non accetta parametri:

gethostname(): string|false

Restituisce una stringa contenente il nome host in caso di successo, oppure false in caso di errore. La funzione è stata introdotta in PHP 5.3 e sostituisce la più vecchia php_uname('n').

Il nome host è il nome della macchina, non il valore dell'intestazione HTTP Host:. Su un server web, gethostname() restituisce il nome del server (ad esempio web-01), mentre il dominio digitato dal visitatore si trova in $_SERVER['HTTP_HOST'].

Esempio di base

Lo script chiede al sistema operativo il nome della macchina locale e lo stampa. L'output esatto dipende da dove viene eseguito il codice — potrebbe essere qualcosa come web-01, localhost, oppure l'ID di un container come a1b2c3d4e5f6.

Gestione sicura degli errori

Poiché gethostname() può restituire false, controlla il risultato prima di usarlo anziché dare per scontato di ottenere sempre una stringa. Usa l'operatore di confronto stretto === per non confondere una stringa vuota con un errore:

<?php

$hostname = gethostname();

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

Quando usarla?

• Logging e diagnostica — aggiungi il tag del server a ogni riga di log, utile soprattutto dietro un load balancer dove molte macchine servono lo stesso sito.
• Chiavi di cache o di lock per host — prefissa i file temporanei o le voci di cache così due server non entrano in conflitto.
• Pagine di salute e stato — mostra agli operatori su quale nodo si trovano.
• Job distribuiti — registra quale worker ha preso in carico un'attività in coda.

gethostname() vs. funzioni correlate

gethostname() risponde solo alla domanda "come si chiama questa macchina?". Per risolvere altri host sulla rete, PHP mette a disposizione funzioni separate:

• gethostbyname() — risolve un nome host in un indirizzo IPv4.
• gethostbyaddr() — risolve inversamente un indirizzo IP in un nome host.
• gethostbynamel() — ottiene l'elenco completo degli indirizzi IPv4 per un nome host.

Un uso frequente è combinarle: ottenere il nome locale e poi risolverlo in un IP:

<?php

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

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

Insidie comuni

• Non è il dominio del client. Non usare gethostname() per rilevare quale sito/dominio ha ricevuto la richiesta; leggi invece $_SERVER['HTTP_HOST'].
• Il valore può essere inatteso nei container. All'interno di Docker il nome host è di solito l'ID del container (generato casualmente), non il nome descrittivo del tuo server.
• Gestisci sempre false. Un sistema mal configurato potrebbe non riuscire a restituire un nome host; proteggiti come mostrato sopra.

Conclusione

gethostname() è una piccola funzione senza parametri che restituisce il nome della macchina che esegue il tuo script, oppure false in caso di errore. Usala per logging, diagnostica e chiavi per host — e ricorri a gethostbyname(), gethostbyaddr() o gethostbynamel() quando hai bisogno di risolvere altri host sulla rete.

Esercitazione