mirror of
https://github.com/php/doc-ru.git
synced 2026-03-25 00:02:09 +01:00
358 lines
15 KiB
XML
358 lines
15 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
||
<!-- EN-Revision: 5c1ccc6e24e5d470e75ef0a5887c2ff583266375 Maintainer: tmn Status: ready -->
|
||
<!-- Reviewed: no -->
|
||
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.header">
|
||
<refnamediv>
|
||
<refname>header</refname>
|
||
<refpurpose>
|
||
Отправляет необработанный HTTP-заголовок
|
||
</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsect1 role="description">
|
||
&reftitle.description;
|
||
<methodsynopsis>
|
||
<type>void</type><methodname>header</methodname>
|
||
<methodparam><type>string</type><parameter>header</parameter></methodparam>
|
||
<methodparam choice="opt"><type>bool</type><parameter>replace</parameter><initializer>&true;</initializer></methodparam>
|
||
<methodparam choice="opt"><type>int</type><parameter>response_code</parameter><initializer>0</initializer></methodparam>
|
||
</methodsynopsis>
|
||
<para>
|
||
Функция <function>header</function> отправляет <acronym>HTTP</acronym>-заголовок.
|
||
<link xlink:href="&url.rfc;2616">Спецификация HTTP/1.1</link>
|
||
подробно описывает <acronym>HTTP</acronym>-заголовки.
|
||
</para>
|
||
<para>
|
||
Помните, функцию <function>header</function> вызывают строго до вывода данных:
|
||
до появления в скрипте HTML-разметки, пустых строк вне режима PHP-кода и до вывода данных функциями или языковыми конструкциями PHP.
|
||
Разработчики часто допускают ошибку, когда выражениями <function>include</function>, <function>require</function>
|
||
или функциями доступа к файлам включают в текущий код внешнее содержимое
|
||
с пробелами или пустыми строками, которые выводятся до вызова
|
||
функции <function>header</function>. Те же проблемы возникают
|
||
при записи в одном файле PHP-кода и HTML-разметки.
|
||
<informalexample>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<html>
|
||
<?php
|
||
|
||
/* Этот пример вызовет ошибку. Обратите внимание
|
||
* на HTML-тег вверху, который выведется до вызова функции header() */
|
||
header('Location: http://www.example.com/');
|
||
exit;
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</informalexample>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="parameters">
|
||
&reftitle.parameters;
|
||
<para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><parameter>header</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Строка заголовка.
|
||
</para>
|
||
<para>
|
||
PHP обрабатывает два заголовка частным способом. Первый —
|
||
регистронезависимый заголовок, который начинается со строки "<literal>HTTP/</literal>".
|
||
Этот заголовок определит код HTTP-статуса для ответа. Например, если веб-сервер Apache
|
||
через директиву <literal>ErrorDocument</literal>
|
||
сконфигурирован на обработку запросов к несуществующим файлам
|
||
PHP-скриптом, то разработчик, вероятно,
|
||
захочет убедиться, что скрипт генерирует правильный код статуса.
|
||
</para>
|
||
<para>
|
||
<informalexample>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?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");
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</informalexample>
|
||
</para>
|
||
<para>
|
||
Другой специфичный вид заголовка — "Location:". Функция не только
|
||
отправляет заголовок в браузер, но и возвращает браузеру 302-й код статуса
|
||
<literal>REDIRECT</literal>, если только прежде не установили код статуса
|
||
<literal>201</literal> или <literal>3xx</literal>.
|
||
</para>
|
||
<para>
|
||
<informalexample>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
header("Location: http://www.example.com/"); /* Перенаправление браузера */
|
||
|
||
/* Исключить выполнение кода после перенаправления .*/
|
||
exit;
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</informalexample>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>replace</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Необязательный параметр <parameter>replace</parameter> определяет,
|
||
заменит ли текущий заголовок предыдущий аналогичный заголовок или требуется добавить второй заголовок того же типа.
|
||
По умолчанию параметр заменит заголовок, но если во втором аргументе передать значение &false;,
|
||
функция принудительно установит серию однотипных заголовков. Например:
|
||
</para>
|
||
<para>
|
||
<informalexample>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
header('WWW-Authenticate: Negotiate');
|
||
header('WWW-Authenticate: NTLM', false);
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</informalexample>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>response_code</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Принудительно задаёт HTTP-код ответа. Обратите внимание, что параметр
|
||
работает, только если строка <parameter>header</parameter> не пуста.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="returnvalues">
|
||
&reftitle.returnvalues;
|
||
<para>
|
||
&return.void;
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="errors">
|
||
&reftitle.errors;
|
||
<para>
|
||
При сбое планирования отправки заголовка функция <function>header</function>
|
||
выдаёт ошибку уровня <constant>E_WARNING</constant>.
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="examples">
|
||
&reftitle.examples;
|
||
<para>
|
||
<example>
|
||
<title>Диалог загрузки</title>
|
||
<para>
|
||
При передаче заголовка <link xlink:href="&url.rfc;2183">Content-Disposition</link>
|
||
клиент предложит пользователю сохранить пересылаемые
|
||
данные, например PDF-файл, который сгенерировал север,
|
||
и покажет в браузере диалог сохранения файла с рекомендуемым названием.
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
// Передача PDF-файла
|
||
header('Content-Type: application/pdf');
|
||
|
||
// Установка названия downloaded.pdf
|
||
header('Content-Disposition: attachment; filename="downloaded.pdf"');
|
||
|
||
// Считывание исходного PDF-файла с названием original.pdf
|
||
readfile('original.pdf');
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
<para>
|
||
<example>
|
||
<title>Директивы для работы с кешем</title>
|
||
<para>
|
||
PHP-скрипты часто генерируют динамическое содержание, которое не должен
|
||
кешировать браузер клиента или промежуточный кеш между сервером
|
||
и клиентским браузером. На прокси-серверах и в браузерах иногда принудительно
|
||
отключают кеширование путём передачи следующих заголовков:
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
|
||
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); // Дата в прошлом
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
<para>
|
||
<note>
|
||
<para>
|
||
Иногда браузер не кеширует страницы
|
||
даже без передачи заголовков с запретом кеширования. Пользователям доступны настройки браузера,
|
||
которые изменяют поведение кеширования по умолчанию.
|
||
Заголовки с явным запретом кеширования переопределят пользовательские настройки,
|
||
которые указывают браузеру кешировать вывод скрипта.
|
||
</para>
|
||
<para>
|
||
Кроме того, через функцию <function>session_cache_limiter</function>
|
||
и директиву <literal>session.cache_limiter</literal> автоматически
|
||
создают правильные заголовки, которые связаны с кешированием при работе с сессиями.
|
||
</para>
|
||
</note>
|
||
</para>
|
||
</example>
|
||
</para>
|
||
<para>
|
||
<example>
|
||
<title>Настройка cookie</title>
|
||
<para>
|
||
Функцией <function>setcookie</function> удобно устанавливать блоки данных cookies.
|
||
Для установки cookie с атрибутами, которые не поддерживает функция <function>setcookie</function>,
|
||
вызывают функцию <function>header</function>.
|
||
</para>
|
||
<para>
|
||
Следующий код, например, устанавливает cookie
|
||
с атрибутом <literal>Partitioned</literal>.
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
header('Set-Cookie: name=value; Secure; Path=/; SameSite=None; Partitioned;');
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="notes">
|
||
&reftitle.notes;
|
||
¬e.network.header.sapi;
|
||
<note>
|
||
<para>
|
||
Проблему обходят путём буферизации вывода скрипта. Тогда
|
||
выводимые данные буферизуются на сервере, пока не появится
|
||
явная команда на пересылку данных. Буферизацией управляют вручную
|
||
функциями <function>ob_start</function> и <function>ob_end_flush</function>,
|
||
либо через директиву <literal>output_buffering</literal> в конфигурационном
|
||
файле &php.ini;, или путём настройки конфигурации сервера.
|
||
</para>
|
||
</note>
|
||
<note>
|
||
<para>
|
||
Строка заголовка с HTTP-статусом отправляется
|
||
клиенту первой, даже если первой вызвали функцию
|
||
<function>header</function>. Статус возможно переопределить в любое время
|
||
вызовом функции <function>header</function> с новой строкой статуса,
|
||
если HTTP-заголовки ещё не отправлялись.
|
||
</para>
|
||
</note>
|
||
<note>
|
||
<para>
|
||
Спецификация протокола HTTP/1.1 требует, чтобы в аргументе
|
||
заголовка <link xlink:href="&spec.http1.1;#section-7.1.2">Location:</link>
|
||
указывали абсолютный <acronym>URI</acronym>,
|
||
который бы включал схему, имя хоста и абсолютный путь, хотя иногда клиенты
|
||
в состоянии принимать и относительные идентификаторы URI. Абсолютный URI возможно построить
|
||
самому через элементы <varname>$_SERVER['HTTP_HOST']</varname>,
|
||
<varname>$_SERVER['PHP_SELF']</varname> или функцией <function>dirname</function>:
|
||
<informalexample>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
/* Перенаправление браузера на другую страницу в той же директории,
|
||
которую запросили */
|
||
$host = $_SERVER['HTTP_HOST'];
|
||
$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
|
||
$extra = 'mypage.php';
|
||
header("Location: http://$host$uri/$extra");
|
||
exit;
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</informalexample>
|
||
</para>
|
||
</note>
|
||
<note>
|
||
<para>
|
||
Идентификатор сессии не передаётся вместе с заголовком Location
|
||
даже при активации настройки <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>.
|
||
Идентификатор потребуется передать вручную через константу <constant>SID</constant>.
|
||
</para>
|
||
</note>
|
||
</refsect1>
|
||
|
||
<refsect1 role="seealso">
|
||
&reftitle.seealso;
|
||
<para>
|
||
<simplelist>
|
||
<member><function>headers_sent</function></member>
|
||
<member><function>setcookie</function></member>
|
||
<member><function>http_response_code</function></member>
|
||
<member><function>header_remove</function></member>
|
||
<member><function>headers_list</function></member>
|
||
<member>
|
||
Раздел документации «<link linkend="features.http-auth">HTTP-аутентификации</link>»
|
||
</member>
|
||
</simplelist>
|
||
</para>
|
||
</refsect1>
|
||
|
||
</refentry>
|
||
<!-- Keep this comment at the end of the file
|
||
Local variables:
|
||
mode: sgml
|
||
sgml-omittag:t
|
||
sgml-shorttag:t
|
||
sgml-minimize-attributes:nil
|
||
sgml-always-quote-attributes:t
|
||
sgml-indent-step:1
|
||
sgml-indent-data:t
|
||
indent-tabs-mode:nil
|
||
sgml-parent-document:nil
|
||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||
sgml-exposed-tags:nil
|
||
sgml-local-catalogs:nil
|
||
sgml-local-ecat-files:nil
|
||
End:
|
||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||
vim: et tw=78 syn=sgml
|
||
vi: ts=1 sw=1
|
||
-->
|