setcookie
Альтернативная сигнатура доступна с PHP 7.3.0 (именованные параметры не поддерживаются):
setcookie() задаёт cookie, которое будет передано клиенту вместе с другими HTTP-заголовками. Как и любой другой заголовок, cookie должны передаваться до того как будут выведены какие-либо другие данные скрипта (это ограничение протокола). Это значит, что в скрипте вызовы этой функции должны располагаться до остального вывода, включая вывод тегов и , а также пустые строки и пробельные символы.
После передачи клиенту cookie станут доступны через массив $_COOKIE при следующей загрузке страницы. Значения cookie также есть в $_REQUEST .
Список параметров
» RFC 6265 даёт конкретные указания, как нужно интерпретировать каждый из параметров setcookie() . name
Значение cookie. Это значение будет сохранено на клиентском компьютере; не записывайте в cookie секретные данные. Значение, присвоенное cookie c именем name , допустим, ‘cookiename’ , будет доступно через $_COOKIE[‘cookiename’] .
Время, когда срок действия 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 делает это преобразование автоматически.
Путь к директории на сервере, из которой будут доступны cookie. Если задать ‘/’ , cookie будут доступны во всем домене domain . Если задать ‘/foo/’ , cookie будут доступны только из директории /foo/ и всех её поддиректорий (например, /foo/bar/ ) домена domain . По умолчанию значением является текущая директория, в которой cookie устанавливается.
(Под)домен, которому доступны cookie. Задание поддомена (например, ‘www.example.com’ ) сделает cookie доступными в нем и во всех его поддоменах (например, w2.www.example.com). Для того, чтобы сделать cookie доступными для всего домена (включая поддомены), нужно просто указать имя домена (то есть ‘example.com’ ).
Старые браузеры, следующие устаревшему документу » RFC 2109, могут требовать . перед доменом, чтобы включались все поддомены.
Указывает на то, что значение cookie должно передаваться от клиента по защищённому соединению HTTPS. Если задано true , cookie от клиента будет передано на сервер, только если установлено защищённое соединение. При передаче cookie от сервера клиенту программист веб-сервера должен следить за тем, чтобы cookie этого типа передавались по защищённому каналу (стоит обратить внимание на $_SERVER[«HTTPS»] ).
Если задано true , cookie будут доступны только через HTTP-протокол. То есть cookie в этом случае не будут доступны скриптовым языкам, вроде JavaScript. Эта возможность была предложена в качестве меры, эффективно снижающей количество краж личных данных посредством XSS-атак (несмотря на то, что поддерживается не всеми браузерами). Стоит однако отметить, что вокруг этой возможности часто возникают споры о её эффективности и целесообразности. Может принимать значения true или false .
Ассоциативный массив ( array ), который может иметь любой из ключей: expires , path , domain , secure , httponly и samesite . При наличии любого другого ключа возникнет ошибка уровня E_WARNING . Значения имеют тот же смысл, как описано в параметрах с соответствующим именем. Значение элемента samesite должно быть либо None , либо Lax , либо Strict . Если какая-либо из допустимых опций не указана, её значения по умолчанию совпадают с значениями по умолчанию для явных параметров. Если элемент samesite не указан, cookie-атрибут SameSite не установлен.
Возвращаемые значения
Если перед вызовом функции клиенту уже передавался какой-либо вывод (теги, пустые строки, пробелы, текст и т.п.), 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. |
Примеры
Ниже представлено несколько примеров, как отправлять cookie:
Пример #1 Пример использования setcookie()
setcookie ( «TestCookie» , $value );
setcookie ( «TestCookie» , $value , time ()+ 3600 ); /* срок действия 1 час */
setcookie ( «TestCookie» , $value , time ()+ 3600 , «/~rasmus/» , «example.com» , 1 );
?>
Стоит отметить, что значение cookie перед отправкой клиенту подвергается URL-кодированию. При обратном получении значение cookie декодируется и помещается в переменную, с тем же именем, что и имя cookie. Если вы не хотите, чтобы значения кодировались, используйте функцию setrawcookie() . Посмотреть содержимое наших тестовых cookie можно, запустив один из следующих примеров:
// Вывести одно конкретное значение cookie
echo $_COOKIE [ «TestCookie» ];
// В целях тестирования и отладки может пригодиться вывод всех cookie
print_r ( $_COOKIE );
?>
Пример #2 Пример удаления cookie посредством setcookie()
Чтобы удалить cookie достаточно в качестве срока действия указать какое-либо время в прошлом. Это запустит механизм браузера, удаляющий истёкшие cookie. В примерах ниже показано, как удалить cookie, заданные в предыдущих примерах:
// установка даты истечения срока действия на час назад
setcookie ( «TestCookie» , «» , time () — 3600 );
setcookie ( «TestCookie» , «» , time () — 3600 , «/~rasmus/» , «example.com» , 1 );
?>
Пример #3 setcookie() и массивы
Имеется возможность помещать в cookie массивы. Для этого каждому cookie нужно дать имя в соответствии с правилами именования массивов. Такая возможность позволяет поместить столько значений, сколько имеется элементов в массиве. При обратном получении все эти значения будут помещены в массив с именем этого cookie:
// отправка 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
\n» ;
>
>
?>
Результат выполнения данного примера:
three : cookiethree two : cookietwo one : cookieone
Замечание: Использование разделительных символов, таких как [ и ] как часть имени файла cookie, не соответствует RFC 6265, раздел 4, но предполагается, что оно поддерживается пользовательскими агентами в соответствии с RFC 6265, раздел 5.
Примечания
Замечание:
Чтобы иметь возможность отправлять вывод скрипта до вызова этой функции, можно воспользоваться буферизацией. В этом случае весь вывод скрипта помещается в буфер на сервере и остаётся там, пока вы явно не отправите его браузеру. Управление буферизацией осуществляется функциями ob_start() и ob_end_flush() в скрипте, либо можно задать директиву output_buffering в файле php.ini или конфигурационных файлах сервера.
- Cookie станут видимыми только после перезагрузки страницы, для которой они должны быть видны. Для проверки, правильно ли cookie установились, проверьте их при следующей загрузке страницы до истечения срока их действия. Срок действия cookie задаётся в параметре expires_or_options . Удобно проверять существование cookie простым вызовом print_r($_COOKIE); .
- При удалении cookie должны быть заданы те же параметры, что и при установке. Если в качестве значения задать пустую строку, а остальные параметры задать соответственно предыдущему вызову, установившему cookie, тогда cookie c заданным именем будет удалено с клиентской машины. Внутренне это выглядит так: cookie присваивается значение ‘deleted’ , а срок действия переносится на год в прошлое.
- Так как установка значения false приведёт к удалению cookie, не следует задавать cookie значения булевого типа. Вместо этого можно использовать 0 для false и 1 для true .
- Cookie можно именовать, как массивы, и они будут доступны в PHP-скрипте, как массивы, но на пользовательской машине они будут храниться в виде отдельных записей. Для задания cookie c множеством имён и значений желательно использовать функцию explode() . Не рекомендуется для этих целей использовать функцию serialize() , так как это негативно сказывается на безопасности скрипта.
При многократных вызовах setcookie() функции выполняются в том порядке, в котором вызывались.
Смотрите также
- header() — Отправка HTTP-заголовка
- setrawcookie() — Отправляет cookie без URL-кодирования значения
- раздел cookies
- » RFC 6265
- » RFC 2109
Как включить COOKIE
Итак мы создали переменную с именем Name, со значением $Сергей.
Теперь везде, где мы сделаем запрос переменной Name, будет выведено Сергей.
Вывод значения cookie
// Вывод одного значения
echo $_COOKIE [ «TestCookie» ];
// вывод всех значений
print_r ( $_COOKIE );
?>
Удалить COOKIE
Или задать время жизни, после которого переменная сама удалится.
Все параметры
setcookie(name, value, expiration time, path, domain);
name — имя переменной;
value — значение этой переменной;
expire — время в секундах с начала эпохи, по истечение которого текущий COOKIE становится не действительным;
path — путь, по которому доступен COOKIE;
domain — домен, из которого доступен COOKIE;
secure — если стоит этот маркер, то информация COOKIE пересылается только через HTTPS (HTTP с использованием SSL — Secure Socket Level), в защищенном режиме. Если этот маркер не указан, то информация пересылается обычным способом.
expire — Время жизни
Время жизни — необязательный параметр, но очень важный, потому что если его не указывать, то переменная проживет до закрытия браузера.
Куки удалятся через час (3600 секунд)
setcookie("Name", "Сергей",time() +3600); Куки удалятся через год (60 секунд * 60 минут * 24 часов * 365 дней)
setcookie("Name", "Сергей",time()+60*60*24*365); Куки удалятся через год в полночь 25 января 2014 года
setcookie("Name", "Сергей", mktime(0,0,0,01,25,2010)); domain
По умолчанию куки читаются на том же домене второго уровня (например, ph4.ru), на котором они созданы. Применяя параметры domain и path, вы можете внести ограничения на использование куки.
setcookie ( «Name» , «Сергей» , time ()+ 3600 , «/dir/» , «www.ph4.ru» );
?> Кука «Name» со значением «Сергей» проживет 1 час, она может читаться только сайтами, размещёнными в директории «/dir/» на домене «www.ph4.ru».
Проверка включены ли COOKIE
- посетитель попадает на страницу, которая задает значения куки,
- затем идет запрос этого значения,
- если переменной нет, то идет переадресация на страницу с текстом вроде «вы сюда попали, потому что у вас отключены COOKIE. Дальше идет описание, как их включить и предупреждение — иначе часть функций на этом сайте вам будет недоступна.
Пример счетчика посещений
$_COOKIE [ «counter» ]++;
setcookie ( «counter» , $counter );
echo «Вы посетили эту страницу » . $_COOKIE [ «counter» ] . » раз» ;
?>