array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'ru', ), 'this' => array ( 0 => 'function.setcookie.php', 1 => 'setcookie', ), 'up' => array ( 0 => 'ref.network.php', 1 => 'Сетевые функции', ), 'prev' => array ( 0 => 'function.pfsockopen.php', 1 => 'pfsockopen', ), 'next' => array ( 0 => 'function.setrawcookie.php', 1 => 'setrawcookie', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'ru', 'path' => 'reference/network/functions/setcookie.xml', ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); ?>
(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); /* срок действия 1 час */
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() выполняются в порядке вызова.