archived-doc-ru/reference/network/functions/setcookie.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 6122a8317ca0068fc71f6a5167e0a2d99166ec7c Maintainer: tmn Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.setcookie" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>setcookie</refname>
  <refpurpose>Отправляет cookie</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>expires_or_options</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>path</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>domain</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>secure</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <simpara>Альтернативная сигнатура доступна с PHP 7.3.0; именованные аргументы не поддерживаются:</simpara>
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <simpara>
   Функция <function>setcookie</function> определяет блок данных cookie, который PHP отправит клиенту вместе
   с остальными HTTP-заголовками. Как и другие заголовки, блоки данных cookies требуется отправлять
   <emphasis>до</emphasis> вывода из скрипта —
   это ограничение протокола. Поэтому функцию вызывают только
   перед выводом, включая вывод тегов <literal>&lt;html&gt;</literal>
   и <literal>&lt;head&gt;</literal> или пробельных символов.
  </simpara>
  <simpara>
   Как только функция установит cookies, доступ к ним откроется
   при следующей загрузке страницы
   через суперглобальную переменную <varname>$_COOKIE</varname>.
   Значения cookie также содержит суперглобальная переменная <varname>$_REQUEST</varname>.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   Стандарт <link xlink:href="&url.rfc;6265">RFC 6265</link> даёт нормативные ссылки
   на интерпретацию значений каждого параметра
   функции <function>setcookie</function>.
   <variablelist>
    <varlistentry>
     <term><parameter>name</parameter></term>
     <listitem>
      <simpara>
       Название cookie.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <simpara>
       Значение cookie. Значение хранится на компьютере клиента;
       поэтому в cookie не записывают конфиденциальную информацию. Значение блока данных cookie,
       для которого через параметр <parameter>name</parameter>
       установили название <literal>'cookiename'</literal>,
       извлекают из элемента <varname>$_COOKIE['cookiename']</varname>.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expires_or_options</parameter></term>
     <listitem>
      <simpara>
       Время истечения срока действия cookie. Метка времени в виде целого числа —
       количества секунд с начала эпохи Unix.
       Значение часто устанавливают путём добавления срока действия cookie в секундах
       к результату вызова функции <function>time</function>.
       Например, выражение <literal>time() + 60 * 60 * 24 * 30</literal> установит
       срок действия cookie, который закончится через 30 дней.
       Другой способ установить срок истечения — вызвать функцию <function>mktime</function>.
       Срок действия cookie закончится с окончанием сессии — при закрытии браузера, —
       если задать значение <literal>0</literal> или опустить аргумент.
      </simpara>
      <note>
       <simpara>
        Параметр <parameter>expires_or_options</parameter> принимает значение в виде метки Unix-времени,
        а не в формате <literal>'Wdy, DD-Mon-YYYY HH:MM:SS GMT'</literal>,
        поскольку PHP автоматически преобразовывает метку
        в формат даты.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <simpara>
       Путь на сервере. Браузер отправит блок данных cookie в запросе только при обращении по заданному пути.
       При установке значения <literal>'/'</literal>
       браузер отправит cookie в каждом запросе к домену <parameter>domain</parameter>.
       При установке значения <literal>'/foo/'</literal>
       cookie отправляются только при обращении к каталогу <literal>/foo/</literal> в домене <parameter>domain</parameter>
       и подкаталогам наподобие <literal>/foo/bar/</literal>.
       По умолчанию cookie устанавливается для текущего каталога.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <simpara>
       Домен или поддомен, для которого требуется установить cookie.
       При установке значения <literal>'www.example.com'</literal>
       cookie отправятся в запросах к поддомену и поддоменам вроде w2.www.example.com.
       Для установки cookie для домена и поддоменов
       указывают имя домена: <literal>'example.com'</literal>.
      </simpara>
      <simpara>
       Старым браузерам, которые до сих пор следуют устаревшему стандарту
       <link xlink:href="&url.rfc;2109">RFC 2109</link>, требуется символ <literal>.</literal>
       перед доменом для сопоставления с поддоменами.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secure</parameter></term>
     <listitem>
      <simpara>
       Указывает, что передавать cookie от клиента требуется
       только по защищённому HTTPS-соединению. При установке значения &true;
       cookie передаются только через безопасное соединение.
       За отправку cookie с сервера только через безопасное соединение отвечает программист.
       Безопасно ли соединение, узнают, например, по значению
       элемента <varname>$_SERVER["HTTPS"]</varname>.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>httponly</parameter></term>
     <listitem>
      <simpara>
       Значение &true; разрешает передачу cookie только по протоколу HTTP
       и закрывает доступ к cookie скриптовым языкам наподобие JavaScript.
       Отдельные разработчики высказывали предположение
       о снижении параметром риска краж личных данных через XSS-атаки.
       При этом не каждый браузер поддерживает параметр,
       а утверждение часто оспаривается. Параметр принимает
       значение &true; или &false;.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <simpara>
       Ассоциативный массив (<type>array</type>) с произвольным набором ключей:
       <literal>expires</literal>, <literal>path</literal>, <literal>domain</literal>,
       <literal>secure</literal>, <literal>httponly</literal> и <literal>samesite</literal>.
      </simpara>
      <simpara>
       Смысл элементов массива аналогичен одноимённым параметрам.
       Элемент <literal>samesite</literal> принимает только следующие значения:
       <literal>None</literal>, <literal>Lax</literal> или <literal>Strict</literal>.
       Пропущенные элементы массива опций получают значение по умолчанию параметра.
       При пропуске элемента <literal>samesite</literal>
       cookie-атрибут SameSite не устанавливается.
      </simpara>
      <note>
       <simpara>
        Cookie с атрибутами вне списка ключей устанавливают
        функцией <function>header</function>.
       </simpara>
      </note>
      <note>
       <simpara>
        При установке для элемента <literal>samesite</literal> значения <literal>"None"</literal>
        потребуется также включить элемент <literal>secure</literal>,
        иначе клиент заблокирует cookie.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   При вызове после сброса вывода функция <function>setcookie</function> завершится ошибкой и вернёт &false;.
   Функция <function>setcookie</function> вернёт &true;, если выполнится без ошибок,
   но это не подтверждает получение cookie пользователем.
  </simpara>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   При включении в массив <parameter>options</parameter> ключей, которые параметр не поддерживает:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     До PHP 8.0.0 функция генерирует ошибку уровня <constant>E_WARNING</constant>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     С PHP 8.0.0 функция выбрасывает ошибку <exceptionname>ValueError</exceptionname>.
    </simpara>
   </listitem>
  </itemizedlist>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.2.0</entry>
      <entry>
       Дата cookie теперь устанавливается в формате <literal>'D, d M Y H:i:s \G\M\T'</literal>;
       раньше дата устанавливалась в формате <literal>'D, d-M-Y H:i:s T'</literal>.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       При передаче в массиве опций ключей, которые параметр не поддерживает, теперь выбрасывается ошибка <exceptionname>ValueError</exceptionname>;
       раньше функция выдавала ошибку уровня <constant>E_WARNING</constant>.
      </entry>
     </row>
     <row>
      <entry>7.3.0</entry>
      <entry>
       Добавили альтернативную сигнатуру, которая поддерживает массив опций <parameter>options</parameter>.
       Эта сигнатура поддерживает также установку cookie-атрибута SameSite.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <simpara>
   Результаты следующих примеров видны в списке блоков данных cookie
   в инструментах разработчика браузера на вкладке Storage или Application.
  </simpara>
  <example>
   <title>Пример отправки cookie функцией <function>setcookie</function></title>
   <programlisting role="php">
<![CDATA[
<?php

$value = 'что-то откуда-то';

// Установка «сессионного блока cookie», срок действия которого истекает при закрытии браузера
setcookie("TestCookie", $value);

// Установка cookie сроком на 1 час
setcookie("TestCookie", $value, time() + 3600);

// Установка cookie, который применяется только к конкретному пути конкретного домена.
// Замечание: браузер отклонит cookie, если домен в пути cookie не совпадёт с доменом сайта
setcookie("TestCookie", $value, time() + 3600, "/~rasmus/", "example.com", true);
]]>
   </programlisting>
  </example>
  <simpara>
   PHP автоматически кодирует и декодирует cookie по правилам безопасного форматирования URL-адресов.
   Функция <function>setrawcookie</function> отправляет cookie без кодирования.
  </simpara>
  <simpara>
   Следующий пример при очередном запросе покажет содержание cookies, которые установили в предыдущем примере:
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php

// Вывод одного конкретного значения cookie
echo $_COOKIE["TestCookie"];

// Вывод всех cookie для тестирования или отладки
print_r($_COOKIE);
]]>
   </programlisting>
  </informalexample>
  <example>
   <title>Пример удаления cookie функцией <function>setcookie</function></title>
   <simpara>
    Для удаления cookie дату истечения срока действия устанавливают как значение в прошлом,
    но не на ноль — значение зарезервировали для сессионных cookie.
   </simpara>
   <simpara>
    Следующий пример удалит cookies, которые установили в предыдущем примере:
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php

// Установка даты истечения срока действия на час в прошлом
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
]]>
   </programlisting>
  </example>
  <example>
   <title>Пример отправки массива cookies функцией <function>setcookie</function></title>
   <simpara>
    Для установки «массива cookies» название cookie указывают в нотации массива.
    Функция установит cookie для каждого элемента массива,
    но скрипт получит значения в едином массиве внутри суперглобального массива, ключ которого совпадает с базовым именем cookie:
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php

// Отправляем cookie
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// Выведем cookie после перезагрузки страницы
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $name => $value) {
        $name = htmlspecialchars($name);
        $value = htmlspecialchars($value);

        echo "$name : $value <br />\n";
    }
}
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
three : cookiethree
two : cookietwo
one : cookieone
]]>
   </screen>
  </example>
  <note>
   <simpara>
    Символы-разделители <literal>[</literal> и <literal>]</literal>
    в составе имени cookie не соответствуют 4-му разделу стандарта RFC 6265,
    но 5-й раздел стандарта RFC 6265 предполагает поддержку таких символов пользовательскими агентами.
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    Буферизация вывода разрешит включить в скрипт конструкции или функции вывода до вызова функции,
    поскольку вывод накапливается в буфере до принудительного сброса или завершения работы скрипта.
    Буферизацией управляют путём вызова функций
    <function>ob_start</function> и <function>ob_end_flush</function> в скрипте,
    включения директивы конфигурации <literal>output_buffering</literal> в файле
    &php.ini; или через файлы конфигурации сервера.
   </simpara>
  </note>
  <para>
   Предостережения:
   <itemizedlist>
    <listitem>
     <simpara>
      Скрипт увидит cookies только при следующей загрузке страницы,
      адрес которой совпадет с путём cookie. Установку cookie
      проверяют по ключу суперглобального массива при следующей загрузке страницы до истечения срока
      действия cookie. Срок действия cookie задают через параметр
      <parameter>expires_or_options</parameter>. Cookies отлаживают
      путём вызова: <literal>print_r($_COOKIE);</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Для удаления cookies потребуется вызывать функцию с теми же аргументами,
      которые указывали при установке. При передаче в аргументе <parameter>value</parameter> пустой строки,
      а в остальных аргументах — значений предыдущего вызова функции <function>setcookie</function>,
      cookie c заданным именем удалится на клиенте;
      cookie удаляется за счёт автоматической установки даты истечения срока действия на значение в прошлом.
      При этом PHP вместо пустого значения подставит значение <literal>'deleted'</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Нельзя указывать для cookie логические значения,
      поскольку установка cookie со значением &false; попытается удалить cookie.
      Вместо &false; указывают значение <emphasis>0</emphasis>, а вместо &true; — <emphasis>1</emphasis>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      При установке через синтаксис массивов PHP-скрипты получают доступ к cookies
      по ключам единого ассоциативного массива, но браузер сохраняет отдельные cookie.
      Один блок cookie с множеством пар «имя — значение» кодируют функцией <function>json_encode</function>,
      но не функцией <function>serialize</function>, поскольку при десериализации
      возникает риск нарушить безопасность.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   Множественные вызовы функции <function>setcookie</function>
   обрабатываются в порядке следования в коде.
  </simpara>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>header</function></member>
   <member><function>setrawcookie</function></member>
   <member><link linkend="features.cookies">Cookies</link></member>
   <member><link xlink:href="&url.rfc;6265">Стандарт RFC 6265</link></member>
   <member><link xlink:href="&url.rfc;2109">Стандарт RFC 2109</link></member>
  </simplelist>
 </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
-->