PHP gethostname(): полное руководство по функции

Функция PHP gethostname() возвращает имя хоста машины, на которой в данный момент выполняется ваш PHP-скрипт — то же имя, которое вы увидите по команде hostname в терминале. Она полезна для записи в журнал информации о том, какой сервер обработал запрос, для построения ключей кэша на основе хоста или для отображения диагностической информации в панели администратора. На этой странице рассмотрены синтаксис, возвращаемые значения (в том числе при ошибке), реальные сценарии использования, распространённые ошибки и связь с другими функциями поиска хоста.

Синтаксис

gethostname() не принимает параметров:

gethostname(): string|false

При успехе возвращает строку с именем хоста, при ошибке — false. Функция появилась в PHP 5.3 и заменяет устаревшую php_uname('n').

Имя хоста — это имя машины, а не значение HTTP-заголовка Host:. На веб-сервере gethostname() вернёт имя сервера (например web-01), тогда как домен, который ввёл пользователь, находится в $_SERVER['HTTP_HOST'].

Базовый пример

Скрипт запрашивает у операционной системы имя локальной машины и выводит его. Конкретный результат зависит от среды выполнения кода — это может быть что-то вроде web-01, localhost или идентификатор контейнера вида a1b2c3d4e5f6.

Безопасная обработка ошибок

Поскольку gethostname() может вернуть false, проверяйте результат перед использованием, а не рассчитывайте всегда получить строку. Используйте строгий оператор ===, чтобы пустая строка не была ошибочно принята за ошибку:

<?php

$hostname = gethostname();

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

Когда это применять?

• Журналирование и диагностика — добавляйте к каждой записи журнала имя сервера, который её создал; это незаменимо за балансировщиком нагрузки, где запросы обрабатывают сразу несколько машин.
• Ключи кэша или блокировок на уровне хоста — добавляйте префикс к временным файлам или записям кэша, чтобы серверы не конфликтовали между собой.
• Страницы состояния и здоровья — показывайте операторам, на каком узле они находятся.
• Распределённые задачи — фиксируйте, какой обработчик взял задачу из очереди.

gethostname() и связанные функции

gethostname() отвечает только на вопрос «как называется эта машина?». Для поиска других хостов в сети PHP предоставляет отдельные функции:

• gethostbyname() — преобразовать имя хоста в IPv4-адрес.
• gethostbyaddr() — выполнить обратное преобразование IP-адреса в имя хоста.
• gethostbynamel() — получить полный список IPv4-адресов для имени хоста.

Распространённый приём — объединить их: получить локальное имя, а затем разрешить его в IP-адрес:

<?php

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

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

Распространённые ошибки

• Это не домен клиента. Не используйте gethostname() для определения сайта или домена, с которого пришёл запрос; для этого читайте $_SERVER['HTTP_HOST'].
• В контейнерах значение может быть неожиданным. Внутри Docker именем хоста обычно служит (случайно сгенерированный) идентификатор контейнера, а не понятное имя сервера.
• Всегда обрабатывайте false. На неправильно настроенной системе функция может не вернуть имя хоста; защищайтесь от этого, как показано выше.

Заключение

gethostname() — небольшая функция без параметров, которая возвращает имя машины, выполняющей скрипт, или false при ошибке. Используйте её для журналирования, диагностики и ключей на уровне хоста, а для поиска других хостов в сети обращайтесь к gethostbyname(), gethostbyaddr() или gethostbynamel().

Практика