Función PHP gethostname(): Todo lo que necesitas saber

La función PHP gethostname() devuelve el nombre del host de la máquina que está ejecutando en ese momento tu script PHP — el mismo nombre que verías con el comando hostname en una terminal. Es muy útil para registrar qué servidor atendió una solicitud, construir claves de caché por host o mostrar información de diagnóstico en un panel de administración. Esta página cubre su sintaxis, qué devuelve (incluso en caso de fallo), casos de uso realistas, errores comunes y su relación con otras funciones de búsqueda de host.

Sintaxis

gethostname() no recibe parámetros:

gethostname(): string|false

Devuelve un string con el nombre del host en caso de éxito, o false en caso de fallo. La función fue introducida en PHP 5.3 y reemplaza al antiguo php_uname('n').

El nombre del host es el nombre de la máquina, no el valor del encabezado HTTP Host:. En un servidor web, gethostname() devuelve el nombre del servidor (por ejemplo web-01), mientras que el dominio que escribió el visitante se encuentra en $_SERVER['HTTP_HOST'].

Ejemplo básico

El script le pregunta al sistema operativo el nombre de la máquina local y lo imprime. El resultado exacto depende de dónde se ejecute el código — podría ser algo como web-01, localhost o un ID de contenedor como a1b2c3d4e5f6.

Manejo seguro de fallos

Dado que gethostname() puede devolver false, verifica el resultado antes de usarlo en lugar de asumir que siempre obtienes un string. Usa el operador estricto === para que un string vacío no se confunda con un fallo:

<?php

$hostname = gethostname();

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

¿Cuándo usarla?

• Registro y diagnóstico — etiqueta cada línea de log con el servidor que la generó, lo cual es muy valioso detrás de un balanceador de carga donde muchas máquinas sirven el mismo sitio.
• Claves de caché o bloqueo por host — añade un prefijo a archivos temporales o entradas de caché para que dos servidores no entren en conflicto.
• Páginas de salud y estado — muestra a los operadores en qué nodo están mirando.
• Trabajos distribuidos — registra qué trabajador recogió una tarea en cola.

gethostname() vs. funciones relacionadas

gethostname() solo responde a "¿cómo se llama esta máquina?". Para buscar otros hosts en la red, PHP proporciona funciones separadas:

• gethostbyname() — resuelve un nombre de host a una dirección IPv4.
• gethostbyaddr() — resuelve de forma inversa una dirección IP a un nombre de host.
• gethostbynamel() — obtiene la lista completa de direcciones IPv4 para un nombre de host.

Un uso habitual es combinarlas — obtener el nombre local y luego resolverlo a una IP:

<?php

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

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

Errores comunes

• No es el dominio del cliente. No uses gethostname() para detectar en qué sitio/dominio llegó una solicitud; lee $_SERVER['HTTP_HOST'] en su lugar.
• El valor puede ser inesperado en contenedores. Dentro de Docker el nombre del host suele ser el ID del contenedor (generado aleatoriamente), no el nombre amigable de tu servidor.
• Maneja siempre false. Un sistema mal configurado puede no reportar un nombre de host; protégete contra ello como se muestra arriba.

Conclusión

gethostname() es una función pequeña y sin parámetros que devuelve el nombre de la máquina que ejecuta tu script, o false en caso de fallo. Úsala para logging, diagnósticos y claves por host — y recurre a gethostbyname(), gethostbyaddr() o gethostbynamel() cuando necesites buscar otros hosts en la red.

Práctica