mirror of
https://github.com/php/doc-ru.git
synced 2026-03-25 16:22:18 +01:00
354 lines
15 KiB
XML
354 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-тегов, пустых строк и т. п.
|
||
Иногда возникает ошибка, когда при чтении кода файловыми функциями наподобие
|
||
<function>include</function> или <function>require</function>
|
||
в коде попадаются пробелы или пустые строки, которые выводятся до вызова
|
||
функции <function>header</function>. Те же проблемы могут возникать,
|
||
когда в одном файле записали PHP-код и HTML-разметку.
|
||
<informalexample>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<html>
|
||
<?php
|
||
|
||
/* Этот пример приведёт к ошибке. Обратите внимание
|
||
* на тег вверху, который будет выведен до вызова функции 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>
|
||
Существует два вызова заголовка, которые отличаются от других. Первый —
|
||
заголовок, который начинается со строки «<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:». Он отправляет
|
||
заголовок обратно в браузер, а также возвращает браузеру код состояния
|
||
<literal>REDIRECT</literal> (302), если только код состояния
|
||
<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>
|
||
Если нужно предложить пользователю сохранить пересылаемые
|
||
данные, например сгенерированный PDF-файл, указывают заголовок
|
||
<link xlink:href="&url.rfc;2183">Content-Disposition</link>, который
|
||
подставляет рекомендуемое имя файла и заставляет браузер показать диалог
|
||
сохранения.
|
||
</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
|
||
-->
|