setcookie

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

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

Описание

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; именованные аргументы не поддерживаются:

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() обрабатываются в порядке следования в коде.

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