(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Отправляет cookie
$name,$value = "",$expires_or_options = 0,$path = "",$domain = "",$secure = false,$httponly = falseАльтернативная сигнатура доступна с PHP 7.3.0 (именованные параметры не поддерживаются):
Функция setcookie() задаёт значение cookie, которое будет отправлено клиенту вместе с другими HTTP-заголовками. Как и другие заголовки, файл cookie должен передаваться до того, как будут выведены любые другие данные скрипта (это ограничение протокола). Для этого нужно вызывать функцию до остального вывода, включая вывод тегов <html> и <head>, а также пустые строки и пробельные символы.
После установки cookie к нему можно будет получить доступ через суперглобальную переменную $_COOKIE при следующей загрузке страницы. Значения cookie также может содержать суперглобальная переменная $_REQUEST.
Стандарт » RFC 6265 даёт конкретные указания о том, как нужно интерпретировать каждый из параметров setcookie().
nameНазвание cookie.
value Значение cookie. Это значение будет сохранено на клиентском компьютере; не записывайте в cookie секретные данные. Значение, присвоенное cookie c именем name, допустим, 'cookiename', будет доступно через $_COOKIE['cookiename'].
expires_or_options Время истечение срока действия cookie. Это метка времени Unix, то есть количество секунд с начала эпохи. Один из способов установить значение — добавить количество секунд до истечения срока действия cookie к результату вызова функции time(). Например, выражение time() + 60 * 60 * 24 * 30 установит срок действия cookie, который закончится через 30 дней. Другой вариант — вызвать функцию mktime(). Если задать 0 или пропустить аргумент, срок действия cookie закончится с окончанием сессии (при закрытии браузера).
Замечание:
Можно заметить, что параметр
expires_or_optionsпринимает в качестве значения метку времени Unix, а хранит его в форматеWdy, DD-Mon-YYYY HH:MM:SS GMT, причина этому то, что PHP делает это преобразование автоматически.
path Путь на сервере, по которому будут доступны значения cookie. Если задать «/», cookie будут доступны во всем домене domain. Если задать «/foo/», cookie будут доступны только из директории /foo/ и её поддиректорий (например, /foo/bar/) домена domain. Значение по умолчанию — текущая директория, в которой PHP устанавливает cookie.
domain Домен или поддомен, которому доступны cookie. Задание поддомена (например, «www.example.com») сделает cookie доступными в нём и во всех поддоменах (например, w2.www.example.com). Чтобы сделать cookie доступными для всего домена, включая поддомены, нужно просто указать имя домена (то есть «example.com»).
Старые браузеры, следующие устаревшему стандарту » RFC 2109, могут требовать . перед доменом, чтобы включались все поддомены.
secure Указывает на то, что значение cookie должно передаваться от клиента по защищённому соединению HTTPS. Если задано true, cookie от клиента будут переданы на сервер, только если установлено защищённое соединение. При передаче cookie от сервера клиенту программист веб-сервера должен следить за тем, чтобы cookie этого типа передавались по защищённому каналу (например, с учётом значения суперглобальной переменной $_SERVER["HTTPS"]).
httponly Если задано true, cookie будут доступны только через HTTP-протокол. То есть cookie не будут доступны скриптовым языкам наподобие JavaScript. Было высказано предположение, что этот параметр в состоянии эффективно уменьшить кражу личных данных через XSS-атаку (хотя он поддерживается не всеми браузерами), но это утверждение часто оспаривается. Может принимать значения true или false.
options Ассоциативный массив (array), который может содержать любой из ключей: expires, path, domain, secure, httponly и samesite. Если в массиве окажется другой ключ, будет выдана ошибка уровня E_WARNING. Значения имеют тот же смысл, который описан для параметров с тем же именем. Значение элемента samesite должно быть либо None, либо Lax или Strict. Если какая-то из разрешённых опций не указана, её значения по умолчанию совпадают с значениями по умолчанию явных параметров. Если элемент samesite не указан, функция не установит cookie-атрибут SameSite.
Замечание:
To set a cookie that includes attributes that aren't among the keys listed, use header().
Если перед вызовом функции клиенту уже передавался какой-либо вывод (теги, пустые строки, пробелы, текст и т.п.), setcookie() потерпит неудачу и вернёт false. Если setcookie() успешно отработает, то вернёт true. Это, однако, не означает, что клиентское приложение (браузер) правильно приняло и обработало cookie.
| Версия | Описание |
|---|---|
| 8.2.0 | Формат даты отправляемых cookie теперь «D, d M Y H:i:s \G\M\T»; ранее он был «D, d-M-Y H:i:s T». |
| 7.3.0 | Добавлена альтернативная подпись, поддерживающая массив опций options. Эта подпись поддерживает также настройку cookie-атрибута SameSite. |
Следующие примеры иллюстрируют ряд способов отправки cookies.
Пример #1 Пример использования setcookie()
<?php
$value = 'что-то откуда-то';
setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);
?>Стоит отметить, что значение cookie перед отправкой клиенту подвергается URL-кодированию. При обратном получении значение cookie декодируется и помещается в переменную, с тем же именем, что и имя cookie. Если вы не хотите, чтобы значения кодировались, используйте функцию setrawcookie(). Посмотреть содержимое наших тестовых cookie можно, запустив один из следующих примеров:
<?php
// Вывести одно конкретное значение cookie
echo $_COOKIE["TestCookie"];
// В целях тестирования и отладки может пригодиться вывод всех cookie
print_r($_COOKIE);
?>Пример #2 Пример удаления cookie посредством setcookie()
Чтобы удалить cookie достаточно в качестве срока действия указать какое-либо время в прошлом. Это запустит механизм браузера, удаляющий истёкшие cookie. В примерах ниже показано, как удалить cookie, заданные в предыдущих примерах:
<?php
// установка даты истечения срока действия на час назад
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>Пример #3 setcookie() и массивы
Имеется возможность помещать в 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 или в файлах конфигурации сервера.
Общие замечания:
expires_or_options. Хороший способ отладить наличие файлов cookie — просто вызывать функцию print_r($_COOKIE);. «deleted», а срок действия переносится на год в прошлое. false приведёт к удалению cookie, не нужно задавать cookie логические значения. Вместо этого можно указать 0 для false и 1 для true. Множественные вызовы функции setcookie() выполняются в порядке вызова.