Отправляет cookie

# setcookie

(PHP 4, PHP 5, PHP 7, PHP 8)

setcookie — Отправляет cookie

### Описание

function setcookie(
string `$name`,
string `$value` = "",
int `$expires_or_options` = 0,
string `$path` = "",
string `$domain` = "",
bool `$secure` = `false`,
bool `$httponly` = `false`
): bool

Альтернативная сигнатура доступна с PHP 7.3.0; именованные аргументы не поддерживаются:

function setcookie(string `$name`, string `$value` = "", array `$options` = []): bool

Функция setcookie() определяет блок данных cookie, который PHP отправит клиенту вместе с остальными HTTP-заголовками. Как и другие заголовки, блоки данных cookies требуется отправлять до вывода из скрипта — это ограничение протокола. Поэтому функцию вызывают только перед выводом, включая вывод тегов `<html>` и `<head>` или пробельных символов.

Как только функция установит cookies, доступ к ним откроется при следующей загрузке страницы через суперглобальную переменную $_COOKIE. Значения cookie также содержит суперглобальная переменная $_REQUEST.

### Список параметров

Стандарт » RFC 6265 даёт нормативные ссылки на интерпретацию значений каждого параметра функции setcookie().

`name`
  Название cookie.
`value`
  Значение cookie. Значение хранится на компьютере клиента; поэтому в cookie не записывают конфиденциальную информацию. Значение блока данных cookie, для которого через параметр `name` установили название `'cookiename'`, извлекают из элемента $_COOKIE['cookiename'].
`expires_or_options`
  Время истечения срока действия cookie. Метка времени в виде целого числа — количества секунд с начала эпохи Unix. Значение часто устанавливают путём добавления срока действия cookie в секундах к результату вызова функции time(). Например, выражение `time() + 60 * 60 * 24 * 30` установит срок действия cookie, который закончится через 30 дней. Другой способ установить срок истечения — вызвать функцию mktime(). Срок действия cookie закончится с окончанием сессии — при закрытии браузера, — если задать значение `0` или опустить аргумент.

  > Замечание: Параметр `expires_or_options` принимает значение в виде метки Unix-времени, а не в формате `'Wdy, DD-Mon-YYYY HH:MM:SS GMT'`, поскольку PHP автоматически преобразовывает метку в формат даты.

`path`
  Путь на сервере. Браузер отправит блок данных cookie в запросе только при обращении по заданному пути. При установке значения `'/'` браузер отправит cookie в каждом запросе к домену `domain`. При установке значения `'/foo/'` cookie отправляются только при обращении к каталогу `/foo/` в домене `domain` и подкаталогам наподобие `/foo/bar/`. По умолчанию cookie устанавливается для текущего каталога.
`domain`
  Домен или поддомен, для которого требуется установить cookie. При установке значения `'www.example.com'` cookie отправятся в запросах к поддомену и поддоменам вроде w2.www.example.com. Для установки cookie для домена и поддоменов указывают имя домена: `'example.com'`. Старым браузерам, которые до сих пор следуют устаревшему стандарту » RFC 2109, требуется символ `.` перед доменом для сопоставления с поддоменами.
`secure`
  Указывает, что передавать cookie от клиента требуется только по защищённому HTTPS-соединению. При установке значения `true` cookie передаются только через безопасное соединение. За отправку cookie с сервера только через безопасное соединение отвечает программист. Безопасно ли соединение, узнают, например, по значению элемента $_SERVER["HTTPS"].
`httponly`
  Значение `true` разрешает передачу cookie только по протоколу HTTP и закрывает доступ к cookie скриптовым языкам наподобие JavaScript. Отдельные разработчики высказывали предположение о снижении параметром риска краж личных данных через XSS-атаки. При этом не каждый браузер поддерживает параметр, а утверждение часто оспаривается. Параметр принимает значение `true` или `false`.
`options`
  Ассоциативный массив (array) с произвольным набором ключей: `expires`, `path`, `domain`, `secure`, `httponly` и `samesite`. Смысл элементов массива аналогичен одноимённым параметрам. Элемент `samesite` принимает только следующие значения: `None`, `Lax` или `Strict`. Пропущенные элементы массива опций получают значение по умолчанию параметра. При пропуске элемента `samesite` cookie-атрибут SameSite не устанавливается.

  > Замечание: Cookie с атрибутами вне списка ключей устанавливают функцией header().

  > Замечание: При установке для элемента `samesite` значения `"None"` потребуется также включить элемент `secure`, иначе клиент заблокирует cookie.

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

При вызове после сброса вывода функция setcookie() завершится ошибкой и вернёт `false`. Функция setcookie() вернёт `true`, если выполнится без ошибок, но это не подтверждает получение cookie пользователем.

### Ошибки

При включении в массив `options` ключей, которые параметр не поддерживает:

- До PHP 8.0.0 функция генерирует ошибку уровня `E_WARNING`.
- С PHP 8.0.0 функция выбрасывает ошибку ValueError.

### Список изменений

Версия | Описание
--- | ---
8.2.0 | Дата cookie теперь устанавливается в формате `'D, d M Y H:i:s \G\M\T'`; раньше дата устанавливалась в формате `'D, d-M-Y H:i:s T'`.
8.0.0 | При передаче в массиве опций ключей, которые параметр не поддерживает, теперь выбрасывается ошибка ValueError; раньше функция выдавала ошибку уровня `E_WARNING`.
7.3.0 | Добавили альтернативную сигнатуру, которая поддерживает массив опций `options`. Эта сигнатура поддерживает также установку cookie-атрибута SameSite.

### Примеры

Результаты следующих примеров видны в списке блоков данных cookie в инструментах разработчика браузера на вкладке Storage или Application.

Пример #1 Пример отправки cookie функцией setcookie()

    <?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);

PHP автоматически кодирует и декодирует cookie по правилам безопасного форматирования URL-адресов. Функция setrawcookie() отправляет cookie без кодирования.

Следующий пример при очередном запросе покажет содержание cookies, которые установили в предыдущем примере:

    <?php

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

    // Вывод всех cookie для тестирования или отладки
    print_r($_COOKIE);

Пример #2 Пример удаления cookie функцией setcookie()

Для удаления cookie дату истечения срока действия устанавливают как значение в прошлом, но не на ноль — значение зарезервировали для сессионных cookie.

Следующий пример удалит cookies, которые установили в предыдущем примере:

    <?php

    // Установка даты истечения срока действия на час в прошлом
    setcookie("TestCookie", "", time() - 3600);
    setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);

Пример #3 Пример отправки массива cookies функцией setcookie()

Для установки «массива cookies» название cookie указывают в нотации массива. Функция установит cookie для каждого элемента массива, но скрипт получит значения в едином массиве внутри суперглобального массива, ключ которого совпадает с базовым именем cookie:

    <?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";
        }
    }

Результат выполнения приведённого примера:

    three : cookiethree
    two : cookietwo
    one : cookieone

> Замечание: Символы-разделители `[` и `]` в составе имени cookie не соответствуют 4-му разделу стандарта RFC 6265, но 5-й раздел стандарта RFC 6265 предполагает поддержку таких символов пользовательскими агентами.

### Примечания

> Замечание: Буферизация вывода разрешит включить в скрипт конструкции или функции вывода до вызова функции, поскольку вывод накапливается в буфере до принудительного сброса или завершения работы скрипта. Буферизацией управляют путём вызова функций ob_start() и ob_end_flush() в скрипте, включения директивы конфигурации `output_buffering` в файле php.ini или через файлы конфигурации сервера.

Предостережения:

- Скрипт увидит cookies только при следующей загрузке страницы, адрес которой совпадет с путём cookie. Установку cookie проверяют по ключу суперглобального массива при следующей загрузке страницы до истечения срока действия cookie. Срок действия cookie задают через параметр `expires_or_options`. Cookies отлаживают путём вызова: `print_r($_COOKIE);`.
- Для удаления cookies потребуется вызывать функцию с теми же аргументами, которые указывали при установке. При передаче в аргументе `value` пустой строки, а в остальных аргументах — значений предыдущего вызова функции setcookie(), cookie c заданным именем удалится на клиенте; cookie удаляется за счёт автоматической установки даты истечения срока действия на значение в прошлом. При этом PHP вместо пустого значения подставит значение `'deleted'`.
- Нельзя указывать для cookie логические значения, поскольку установка cookie со значением `false` попытается удалить cookie. Вместо `false` указывают значение 0, а вместо `true` — 1.
- При установке через синтаксис массивов PHP-скрипты получают доступ к cookies по ключам единого ассоциативного массива, но браузер сохраняет отдельные cookie. Один блок cookie с множеством пар «имя — значение» кодируют функцией json_encode(), но не функцией serialize(), поскольку при десериализации возникает риск нарушить безопасность.

Множественные вызовы функции setcookie() обрабатываются в порядке следования в коде.

### Смотрите также

- header() - Отправляет необработанный HTTP-заголовок
- setrawcookie() - Отправляет cookie без URL-кодирования значения
- Cookies
- » Стандарт RFC 6265
- » Стандарт RFC 2109

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open