Função PHP gethostname(): Tudo o Que Você Precisa Saber

A função PHP gethostname() retorna o nome do host da máquina que está executando atualmente o seu script PHP — o mesmo nome que você veria com o comando hostname em um terminal. É útil para registrar qual servidor tratou uma requisição, construir chaves de cache por host ou exibir informações de diagnóstico em um painel administrativo. Esta página aborda sua sintaxe, o que ela retorna (inclusive em caso de falha), casos de uso realistas, armadilhas comuns e como ela se relaciona com outras funções de busca de host.

Sintaxe

gethostname() não recebe parâmetros:

gethostname(): string|false

Ela retorna uma string contendo o nome do host em caso de sucesso, ou false em caso de falha. A função foi introduzida no PHP 5.3 e substitui o antigo php_uname('n').

O nome do host é o nome da máquina, não o valor do cabeçalho HTTP Host:. Em um servidor web, gethostname() retorna o nome do servidor (por exemplo web-01), enquanto o domínio digitado pelo visitante está em $_SERVER['HTTP_HOST'].

Exemplo básico

O script solicita ao sistema operacional o nome da máquina local e o imprime. A saída exata depende de onde o código é executado — pode ser algo como web-01, localhost ou um ID de contêiner como a1b2c3d4e5f6.

Tratando falhas com segurança

Como gethostname() pode retornar false, verifique o resultado antes de utilizá-lo em vez de assumir que sempre receberá uma string. Use o operador estrito === para que uma string vazia não seja confundida com falha:

<?php

$hostname = gethostname();

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

Quando eu usaria isso?

• Log e diagnóstico — marque cada linha de log com o servidor que a gerou, o que é indispensável atrás de um balanceador de carga onde várias máquinas atendem o mesmo site.
• Chaves de cache ou bloqueio por host — prefixe arquivos temporários ou entradas de cache para que dois servidores não entrem em conflito.
• Páginas de saúde e status — mostre aos operadores qual nó estão visualizando.
• Jobs distribuídos — registre qual worker capturou uma tarefa na fila.

gethostname() vs. funções relacionadas

gethostname() responde apenas "como esta máquina se chama?". Para buscar outros hosts na rede, o PHP fornece funções separadas:

• gethostbyname() — resolve um nome de host para um endereço IPv4.
• gethostbyaddr() — faz a resolução reversa de um endereço IP para um nome de host.
• gethostbynamel() — obtém a lista completa de endereços IPv4 para um nome de host.

Um uso comum subsequente é combiná-las — obter o nome local e então resolvê-lo para um IP:

<?php

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

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

Armadilhas comuns

• Não é o domínio do cliente. Não use gethostname() para detectar qual site/domínio chegou em uma requisição; leia $_SERVER['HTTP_HOST'] em vez disso.
• O valor pode ser inesperado em contêineres. Dentro do Docker, o nome do host geralmente é o ID do contêiner (gerado aleatoriamente), não o nome amigável do seu servidor.
• Sempre trate o false. Um sistema mal configurado pode falhar ao reportar um nome de host; proteja-se contra isso conforme mostrado acima.

Conclusão

gethostname() é uma função pequena e sem parâmetros que retorna o nome da máquina que executa seu script, ou false em caso de falha. Use-a para logging, diagnósticos e chaves por host — e recorra a gethostbyname(), gethostbyaddr() ou gethostbynamel() quando precisar buscar outros hosts na rede.

Prática