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 с именем 'cookiename', которое установили через параметр name, получают через элемент массива $_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, если задать значение «/». Сервер откроет доступ к блоку данных cookie в домене domain только в каталоге /foo/ и каждом подкаталоге вроде /foo/bar/, если задать значение «/foo/». Значение по умолчанию — текущий каталог, в которой PHP устанавливает cookie.

domain

Домен или поддомен, у которого будет доступ к блоку данных cookie. При установке параметра на поддомен www.example.com сервер откроет доступ к cookie для этого поддомена и каждого его поддомена наподобие w2.www.example.com. Чтобы открыть доступ к cookie для всего домена с поддоменами, нужно просто указать имя домена (для этого примера — example.com).

Старым браузерам, которые до сих пор следуют устаревшему стандарту » RFC 2109, иногда требуется символ . перед доменом для соответствия каждому поддомену.

secure

Указывает, что передавать блок данных cookie от клиента требуется только по защищённому HTTPS-соединению. PHP установит cookie только через безопасное соединение, если для параметра установили значение true. За отправку cookie с сервера только через безопасное соединение отвечает программист. Безопасно ли подключение, узнают, например, по значению суперглобальной переменной $_SERVER["HTTPS"].

httponly

PHP предоставит доступ к cookie только через HTTP-протокол, если для параметра установили значение true. Это означает, что скриптовые языки наподобие JavaScript не получат доступа к cookie. Отдельные программисты высказывали предположение, что этот параметр в состоянии эффективно сократить количество краж личных данных через XSS-атаки (хотя параметр поддерживается не каждым браузером), но это утверждение часто оспаривается. Параметр принимает значение true или false.

options

Ассоциативный массив (array) с произвольным набором ключей из следующего списка: expires, path, domain, secure, httponly и samesite. Функция выдаст ошибку уровня E_WARNING, если в массиве окажется другой ключ. Значения несут тот же смысл, который описали в параметрах с тем же именем. Элемент samesite принимает только следующие значения: None, Lax или Strict. Значения разрешённых опций, которые не указали, по умолчанию совпадают со значениями по умолчанию явных параметров. Функция не устанавливает cookie-атрибут SameSite, если элемент samesite не указали.

Замечание:

Блок данных cookie с атрибутами, которых нет в списке ключей, устанавливают функцией 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", true);

?>

Обратите внимание, что функция автоматически URL-кодирует часть значения cookie перед отправкой клиенту, а когда получает cookie — автоматически декодирует часть значения и присваивает переменной с тем же именем, что и имя cookie. Если URL-кодирование значения не нужно, вызывают функцию 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, сколько элементов массива, но когда скрипт получит 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 или в файлах конфигурации сервера.

Общие замечания:

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

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

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