(PHP 4, PHP 5, PHP 7, PHP 8)
header — Отправляет необработанный HTTP-заголовок
Функция header() отправляет HTTP-заголовок. » Спецификация HTTP/1.1 подробно описывает HTTP-заголовки.
Помните, функцию header() вызывают строго до вывода данных: до появления в скрипте HTML-разметки, пустых строк вне режима PHP-кода и до вывода данных функциями или языковыми конструкциями PHP. Разработчики часто допускают ошибку, когда выражениями include, require или функциями доступа к файлам включают в текущий код внешнее содержимое с пробелами или пустыми строками, которые выводятся до вызова функции header(). Те же проблемы возникают при записи в одном файле PHP-кода и HTML-разметки.
<html>
<?php
/* Этот пример вызовет ошибку. Обратите внимание
* на HTML-тег вверху, который выведется до вызова функции header() */
header('Location: http://www.example.com/');
exit;
?>
headerСтрока заголовка.
PHP обрабатывает два заголовка частным способом. Первый —
регистронезависимый заголовок, который начинается со строки "HTTP/".
Этот заголовок определит код HTTP-статуса для ответа. Например, если веб-сервер Apache
через директиву ErrorDocument
сконфигурирован на обработку запросов к несуществующим файлам
PHP-скриптом, то разработчик, вероятно,
захочет убедиться, что скрипт генерирует правильный код статуса.
<?php
// Пример иллюстрирует передачу заголовка "HTTP/" с жёстоко заданной версией протокола.
//
// Из альтернативных способов указать правильную версию протокола
// в типичных случаях вместо установки версии вручную выбирают следующее:
// 1. header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found");
// Вызов переопределяет сообщение об HTTP-статусе для клиентов, которые всё ещё работают по протоколу HTTP/1.0
//
// 2. http_response_code(404);
// Вызов установит код ответа, а сервер отправит стандартное сообщение о статусе
// и версию протокола
header("HTTP/1.1 404 Not Found");
?>
Другой специфичный вид заголовка — "Location:". Функция не только
отправляет заголовок в браузер, но и возвращает браузеру 302-й код статуса
REDIRECT, если только прежде не установили код статуса
201 или 3xx.
<?php
header("Location: http://www.example.com/"); /* Перенаправление браузера */
/* Исключить выполнение кода после перенаправления .*/
exit;
?>replace
Необязательный параметр replace определяет,
заменит ли текущий заголовок предыдущий аналогичный заголовок или требуется добавить второй заголовок того же типа.
По умолчанию параметр заменит заголовок, но если во втором аргументе передать значение false,
функция принудительно установит серию однотипных заголовков. Например:
<?php
header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM', false);
?>response_code
Принудительно задаёт HTTP-код ответа. Обратите внимание, что параметр
работает, только если строка header не пуста.
Функция не возвращает значения после выполнения.
При сбое планирования отправки заголовка функция header()
выдаёт ошибку уровня E_WARNING.
Пример #1 Диалог загрузки
При передаче заголовка » Content-Disposition клиент предложит пользователю сохранить пересылаемые данные, например PDF-файл, который сгенерировал север, и покажет в браузере диалог сохранения файла с рекомендуемым названием.
<?php
// Передача PDF-файла
header('Content-Type: application/pdf');
// Установка названия downloaded.pdf
header('Content-Disposition: attachment; filename="downloaded.pdf"');
// Считывание исходного PDF-файла с названием original.pdf
readfile('original.pdf');
?>
Пример #2 Директивы для работы с кешем
PHP-скрипты часто генерируют динамическое содержание, которое не должен кешировать браузер клиента или промежуточный кеш между сервером и клиентским браузером. На прокси-серверах и в браузерах иногда принудительно отключают кеширование путём передачи следующих заголовков:
<?php
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); // Дата в прошлом
?>
Замечание:
Иногда браузер не кеширует страницы даже без передачи заголовков с запретом кеширования. Пользователям доступны настройки браузера, которые изменяют поведение кеширования по умолчанию. Заголовки с явным запретом кеширования переопределят пользовательские настройки, которые указывают браузеру кешировать вывод скрипта.
Кроме того, через функцию session_cache_limiter() и директиву
session.cache_limiterавтоматически создают правильные заголовки, которые связаны с кешированием при работе с сессиями.
Пример #3 Настройка cookie
Функцией setcookie() удобно устанавливать блоки данных cookies. Для установки cookie с атрибутами, которые не поддерживает функция setcookie(), вызывают функцию header().
Следующий код, например, устанавливает cookie
с атрибутом Partitioned.
<?php
header('Set-Cookie: name=value; Secure; Path=/; SameSite=None; Partitioned;');
?>Замечание:
Заголовки доступны и выводятся, только если PHP работает через SAPI-интерфейс с поддержкой заголовков.
Замечание:
Проблему обходят путём буферизации вывода скрипта. Тогда выводимые данные буферизуются на сервере, пока не появится явная команда на пересылку данных. Буферизацией управляют вручную функциями ob_start() и ob_end_flush(), либо через директиву
output_bufferingв конфигурационном файле php.ini, или путём настройки конфигурации сервера.
Замечание:
Строка заголовка с HTTP-статусом отправляется клиенту первой, даже если первой вызвали функцию header(). Статус возможно переопределить в любое время вызовом функции header() с новой строкой статуса, если HTTP-заголовки ещё не отправлялись.
Замечание:
Спецификация протокола HTTP/1.1 требует, чтобы в аргументе заголовка » Location: указывали абсолютный URI, который бы включал схему, имя хоста и абсолютный путь, хотя иногда клиенты в состоянии принимать и относительные идентификаторы URI. Абсолютный URI возможно построить самому через элементы $_SERVER['HTTP_HOST'], $_SERVER['PHP_SELF'] или функцией dirname():
<?php
/* Перенаправление браузера на другую страницу в той же директории,
которую запросили */
$host = $_SERVER['HTTP_HOST'];
$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
$extra = 'mypage.php';
header("Location: http://$host$uri/$extra");
exit;
?>
Замечание:
Идентификатор сессии не передаётся вместе с заголовком Location даже при активации настройки session.use_trans_sid. Идентификатор потребуется передать вручную через константу
SID.