January 27th, 2010

Отправка сырого HTTP-заголовка. Функция Header

Сегодня в каталог статей добавил мой перевод документации по PHP функции Header

Отправка сырого HTTP-заголовка. Функция Header

v:1.0 27.01.2010

Перевод официальной документации.

header

(PHP 4, PHP 5)

header — отправляет сырой HTTP-заголовок.</p>

Описание

void header(string $string [, bool $replace = true [, int $http_response_code]])</br> Функция header() используется для отправки сырого (необработанного) HTTP заголовка. Дополнительную информацию о заголовке HTTP смотрите в спецификации HTTP/1.1

Помните, что функция header() должна вызываться до любой другой директивы, например обычного тега HTML, пустой строки в файле или PHP-формы. Очень часто встречается ошибка, когда перед функцией header() вызываются функции include(), require() или другие функции для доступа к файлам, или вставляются пустые строки и пробелы.</br> Эта же проблема появляется, при использовании единых файлов PHP/HTML. </br></br> Пример </br> <html>
<?php
/* Этот код вернет ошибку, т.к. до вызова header() встречается тег HTML*/
header('Location: http://www.example.com/');
?>

Параметры

string

Строка заголовка.

Возможны два варианта вызова функции header().</br> Первый вариант - вызов функции со строкой (параметр string) "HTTP/" (регистр не имеет значения), которая укажет код HTTP статуса. Например, если Вы в Apache сконфигурировали PHP-скрип для обработки ошибки типа "запрашиваемый файл не найден" (директива ErrorDocument), то у Вас есть возможность убедиться, что Ваш скрипт генерирует правильный код статуса.

<?php
header("HTTP/1.0 404 Not Found");
?>

Второй вариант вызова - использование в заголовке строки "Location:".</br> В этом случае функция не только возвращает заголовок в браузер, но и возвращает код статуса REDIRECT (302), если уже не установлен код 201 или 3xx

<?php
header("Location: http://www.example.com/"); /* Перенаправление браузера */

/* Убедитесь, что последующий код не выполняется после перенаправления*/
exit;
?>

replace

Необязательный параметр replace (замена) определяет надо ли заменить предыдущий похожий заголовок или добавить следующий того же типа. По умолчанию заголовок будет заменен. Однако, если Вы передадите значение FALSE, то можете создать несколько заголовков одного типа.</br> Например:

<?php
header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM'false);
?>

http_response_code

Принудительная установка значения HTTP код ответа.

Возвращаемые значения

Функция не возвращает никакие значения.

Хронология изменений

ВерсияОписание
4.4.2 и 5.1.2 Устранена возможность отправки нескольких заголовков за раз, это позволило повысить защиту от инъекционных атак (injection attacks)
4.3.0 Добавлен параметр http_response_code
4.0.4 Добавлен параметр replace

Примеры

Пример #1 Диалог загрузки

Если вы хотите сообщить пользователю, какого типа данные отправляете (например сгенерированный PDF файл ), то можете использовать заголовок Content-Disposition, в котором будут указаны предлагаемое имя файла и команда браузеру отрисовать диалог сохранения файла.

<?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"); //Дата в прошлом
?>

Примечание: Вы можете обнаружить, что Ваши страницы не кэшруются даже если Вы не выполнили приведенные выше функции. Пользователь может поменять настройки браузера и таким образом изменить работу механизма кэширования.</br> Отправив приведенные выше заголовки, вы перекроете любые настройки, которые могут управлять кэшированием страниц.
И еще пара слов... Если используются сессии, с помощью конфигурационных параметров session_cache_limiter() и session.cache_limiter можно настроить корректную генерацию кэш-ориентированных заголовков.

Примечания

Примечание: Строка HTTP статуса заголовка всегда первой посылается клиенту, независимо от того является ли вызов header() первым или нет. Пока HTTP заголовки не установлены статус может быть изменен вызовом header() с новой строкой статуса.

Примечание: Если Вы устанавливаете WWW-Authenticate заголовок (используете HTTP Authentication) и включен режим safe mode, то uid скрипта добавится в часть realm заголовка WWW-Authenticate.

Примечание: Стандарт 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;
?>

Примечание: Session ID (ID сессии) не передается в заголовке Location даже если включен session.use_trans_sid. Session ID должен передаваться вручную, для этого надо использовать константу SID.

Петрелевич Сергей
petrelevich@yandex.ru
www.SmartyIT.ru