setcookie
(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Отправляет cookie
Описание
Альтернативная сигнатура доступна с PHP 7.3.0; именованные аргументы не поддерживаются:
Функция 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.
Примеры
Результаты следующих примеров видны в списке блоков данных 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, которые установили в предыдущем примере:
Пример #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()
обрабатываются в порядке следования в коде.