Функция headers_list() в PHP: всё что нужно знать

Каждый PHP-ответ содержит набор HTTP-заголовков — таких как Content-Type, Set-Cookie и любые пользовательские значения, которые вы добавляете. Функция headers_list() позволяет проверить этот набор изнутри скрипта: она возвращает заголовки, которые PHP собирается отправить (или уже отправил) клиенту. Это незаменимо для отладки редиректов, типов контента и cookie до того, как ответ будет отправлен.

На этой странице рассматривается, что возвращает headers_list(), когда эти заголовки фактически существуют, в чём разница между ней и headers_sent(), а также практические паттерны её использования.

Синтаксис

headers_list(): array

headers_list() не принимает никаких параметров и возвращает индексированный array строк. Каждая строка представляет собой одну строку заголовка в точном виде, в котором она будет отправлена, например Content-Type: text/html; charset=UTF-8. Если заголовки ещё не были установлены, возвращается пустой массив.

Простой пример

Функция отражает все заголовки, которые PHP планирует отправить в данный момент. Сначала установите несколько заголовков с помощью header(), затем выведите их список:

<?php

header('Content-Type: application/json');
header('X-Powered-By: w3docs');

$headers = headers_list();
foreach ($headers as $header) {
    echo $header, "\n";
}

Типичный вывод (конкретный набор зависит от вашей конфигурации PHP/сервера):

Content-Type: application/json
X-Powered-By: w3docs

PHP часто добавляет собственные заголовки по умолчанию (например, Content-Type и X-Powered-By) до выполнения вашего кода, поэтому список может содержать записи, которые вы явно не устанавливали.

Когда заголовки доступны?

headers_list() отражает только те заголовки, которые PHP хранит во внутреннем буфере. Это имеет два важных следствия:

• Функция сообщает о заголовках независимо от того, были ли они отправлены или нет. Используйте её вместе с headers_sent(), если нужно знать, был ли буфер уже сброшен.
• Функция работает только на стороне сервера. Она не возвращает заголовки запроса, отправленные браузером — для этого используйте getallheaders() или суперглобальную переменную $_SERVER.

Проверка наличия конкретного заголовка

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

<?php

header('Location: /dashboard');

$hasLocation = false;
foreach (headers_list() as $header) {
    if (stripos($header, 'Location:') === 0) {
        $hasLocation = true;
        break;
    }
}

echo $hasLocation ? "Redirect header is set\n" : "No redirect header\n";

Вывод:

Redirect header is set

stripos(..., 'Location:') === 0 выполняет поиск без учёта регистра в начале строки, поскольку имена заголовков не чувствительны к регистру.

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

Поскольку headers_list() работает только на чтение, её можно безопасно вызывать в любой точке — она никогда не вызывает предупреждение «headers already sent», которое может возникнуть при вызове header().

Распространённые случаи использования

• Отладка: выводите headers_list() в процессе разработки, чтобы видеть именно то, что отправляет сервер, включая cookie, установленные через setcookie().
• Условная логика: добавляйте заголовок только в том случае, если он ещё не присутствует.
• Тестирование: проверяйте, что контроллер сформировал ожидаемый Content-Type или Cache-Control.

Заключение

headers_list() предоставляет снимок HTTP-заголовков ответа, которые PHP намерен отправить, доступный только для чтения. Используйте её вместе с headers_sent() для проверки времени отправки, header() для установки значений и header_remove() для их удаления. Вместе эти функции дают вам полный контроль над заголовками ответа до того, как они достигнут браузера.

Практика