(PHP 4, PHP 5, PHP 7)
setcookie — Отправляет cookie
$name
[, string $value = ""
[, int $expire = 0
[, string $path = ""
[, string $domain = ""
[, bool $secure = false
[, bool $httponly = false
]]]]]] )setcookie() задает cookie, которое будет передано клиенту вместе с другими HTTP-заголовками. Как и любой другой заголовок, cookie должны передаваться до того как будут выведены какие-либо другие данные скрипта (это ограничение протокола). Это значит, что в скрипте вызовы этой функции должны располагаться до остального вывода, включая вывод тегов <html> и <head>, а также пустые строки и пробельные символы.
После передачи клиенту cookie станут доступны через массив $_COOKIE при следующей загрузке страницы. Значения cookie также есть в $_REQUEST.
» RFC 6265 дает конкретные указания, как нужно интерпретировать каждый из параметров setcookie().
nameНазвание cookie.
value
Значение cookie. Это значение будет сохранено на клиентском компьютере; не
записывайте в cookie секретные данные. Значение присвоенное cookie c именем
name, допустим, 'cookiename', будет
доступно через $_COOKIE['cookiename'].
expireВремя, когда срок действия cookie истекает. Это метка времени Unix, то есть количество секунд с начала эпохи. Другими словами, желательно задавать это время с помощью функции time(), прибавляя время в секундах, через которое срок действия cookie должен истечь. Либо можно воспользоваться функцией mktime(). time()+60*60*24*30 установит срок действия cookie 30 дней. Если задать 0 или пропустить этот аргумент, срок действия cookie истечет с окончанием сессии (при закрытии браузера).
Замечание:
Можно заметить, что
expireпринимает в качестве значения метку времени Unix, а хранит его в формате Wdy, DD-Mon-YYYY HH:MM:SS GMT. PHP делает это преобразование автоматически.
path
Путь к директории на сервере, из которой будут доступны cookie. Если задать
'/', cookie будут доступны во всем домене
domain. Если задать '/foo/',
cookie будут доступны только из директории /foo/ и всех
ее поддиректорий (например, /foo/bar/) домена
domain. По умолчанию значением является текущая
директория, в которой 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-атак (несмотря
на то, что поддерживается не всеми браузерами). Стоит однако же отметить, что
вокруг этой возможности часто возникают споры о ее эффективности и
целесообразности. Аргумент добавлен в PHP 5.2.0. Может принимать
значения TRUE или FALSE.
Если перед вызовом функции клиенту уже передавался какой-либо вывод (теги,
пустые строки, пробелы, текст и т.п.),
setcookie() потерпит неудачу и вернет FALSE. Если
setcookie() успешно отработает, то вернет TRUE.
Это, однако, не означает, что клиентское приложение (браузер) правильно приняло
и обработало cookie.
Ниже представлено несколько примеров, как отправлять cookie:
Пример #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() (работает в PHP 5). Посмотреть содержимое наших тестовых 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
| Версия | Описание |
|---|---|
| 5.5.0 | Теперь атрибут max-age включен в заголовок, отправляемый клиенту Set-Cookie. |
| 5.2.0 |
Добавлен параметр httponly.
|
Замечание:
Чтобы иметь возможность отправлять вывод скрипта до вызова этой функции, можно воспользоваться буферизацией. В этом случае весь вывод скрипта помещается в буфер на сервере и остается там, пока вы явно не отправите его браузеру. Управление буферизацией осуществляется функциями ob_start() и ob_end_flush() в скрипте, либо можно задать директиву output_buffering в файле php.ini или конфигурационных файлах сервера.
Замечание:
Если PHP-директива register_globals включена (задано значение on), значения cookie помимо всего прочего будут помещаться в переменные. Для примеров выше будет существовать переменная $TestCookie. Тем не менее, рекомендуется использовать $_COOKIE.
Общие замечания:
expire. Удобно проверять существование cookie простым
вызовом print_r($_COOKIE);.
FALSE,
а остальные параметры задать соответственно предыдущему вызову,
установившему cookie, тогда cookie c заданным именем будет удалено с
клиентской машины. Внутренне это выглядит так: cookie присваивается значение
'deleted', а срок действия переносится на год в прошлое.
FALSE приведет к удалению cookie, не следует
задавать cookie значения булевого типа. Вместо этого можно использовать
0 для FALSE и 1 для TRUE.
При многократных вызовах setcookie() функции выполняются в том порядке, в котором вызывались.