setcookie
setcookie() задает cookie, которое будет передано клиенту вместе с другими HTTP заголовками. Как и любой другой заголовок, cookie должны передаваться до того как будут выведены какие-либо другие данные скрипта (это ограничение протокола). Это значит, что в скрипте вызовы этой функции должны располагаться прежде остального вывода, включая вывод тэгов <html> и <head>, а также пустые строки и пробелы.
После передачи клиенту cookie станут доступны через массивы $_COOKIE и $HTTP_COOKIE_VARS при следующей загрузке страницы. Следует иметь в виду, что суперглобальные переменные, такие как $_COOKIE , стали доступны только в PHP 4.1.0. Значения cookie также есть в $_REQUEST .
Список параметров
Все аргументы, за исключением name , являются необязательными. Если нужно пропустить какой-либо аргумент, можно вместо него поставить пустую строку (""). Это не относится к аргументу expire . Так как он принимает значение типа integer, для его замены пустая строка не подходит. Используйте вместо нее ноль (0).
» RFC 6265 дает конкретные указания, как нужно интерпретировать каждый из параметров setcookie() . name
Значение cookie. Это значение будет сохранено на клиентском компьютере; не записывайте в cookie секретные данные. Значение присвоенное cookie c именем name , допустим, 'cookiename', будет доступно через $_COOKIE[‘cookiename’] .
Время, когда срок действия 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 делает внутреннее преобразование автоматически.
Путь к директории на сервере, из которой будут доступны cookie. Если задать '/', cookie будут доступны во всем домене domain . Если задать '/foo/', cookie будут доступны только из директории /foo/ и всех ее поддиректорий (например, /foo/bar/) домена domain . По умолчанию значением является текущая директория, в которой cookie устанавливается.
Домен, которому доступны cookie. Задание домена 'www.example.com' сделает cookie доступными в поддомене www и поддоменах более высоких порядков. Cookie доступные низким уровням, таким как 'example.com', будут доступны во всех поддоменах высших уровней, с том числе 'www.example.com'. Старые броузеры, следующие устаревшим нормативам » RFC 2109, могут требовать . перед доменом, чтобы включались все поддомены.
Указывает на то, что значение cookie должно передаваться от клиента по защищенному HTTPS соединению. Если задано TRUE , cookie от клиента будет передано на сервер, только если установлено защищенное соединение. При передаче cookie от сервера клиенту следить за тем, чтобы cookie этого типа передавались по защищенному каналу, должен программист веб-сервера (стоит обратить внимание на $_SERVER[«HTTPS»] ).
Если задано 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 , «/
Стоит отметить, что значение cookie перед отправкой клиенту подвергается URL-кодированию. При обратном получении значение cookie декодируется и помещается в переменную, с тем же именем, что и имя cookie. Если вы не хотите, чтобы значения кодировались, используйте функцию setrawcookie() (работает в PHP 5). Посмотреть содержимое наших тестовых cookie можно, запустив один из следующих примеров:
<?php
// Вывести одно конкретное значение cookie
echo $_COOKIE [ «TestCookie» ];
echo $HTTP_COOKIE_VARS [ «TestCookie» ];
// В целях тестирования и отладки может пригодиться вывод всех cookie
print_r ( $_COOKIE );
?>
Пример #2 Пример удаления cookie посредством setcookie()
Чтобы удалить cookie достаточно в качестве срока действия указать какое-либо время в прошлом. Это запустит механизм броузера, удаляющий истекшие cookie. В примерах ниже показано, как удалить cookie, заданные в предыдущих примерах:
Пример #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» ;
>
>
?>
Результат выполнения данного примера:
Список изменений
| Версия | Описание |
|---|---|
| 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 .
- Cookie станут видимыми только после перезагрузки страницы, для которой они должны быть видны. Для проверки, правильно ли cookie установились, проверьте их при следующей загрузке страницы до истечения срока их действия. Срок действия cookie задается в параметре expire . Удобно проверять существование cookie простым вызовом print_r($_COOKIE);.
- При удалении cookie должны быть заданы те же параметры, что и при установке. Если в качестве значения задать пустую строку или FALSE , а остальные параметры задать соответственно предыдущему вызову, установившему cookie, тогда cookie c заданным именем будет удалено с клиентской машины. Внутренне это выглядит так: cookie присваивается значение 'deleted', а срок действия переносится на год в прошлое.
- Так как установка значения FALSE приведет к удалению cookie, не следует задавать cookie значения булевого типа. Вместо этого можно использовать 0 для FALSE и 1 для TRUE .
- Cookie можно именовать, как массивы, и они будут доступны в PHP скрипте, как массивы, но на пользовательской машине они будут храниться в виде отдельных записей. Для задания cookie c множеством имен и значений желательно использовать функцию explode() . Не рекомендуется для этих целей использовать функцию serialize() , так как это негативно сказывается на безопасности скрипта.
При многократных вызовах setcookie() функции выполняются в том порядке, в котором вызывались.
PHP setcookie() Function
The following example creates a cookie named "user" with the value "John Doe". The cookie will expire after 30 days (86400 * 30). The "/" means that the cookie is available in entire website (otherwise, select the directory you prefer).
We then retrieve the value of the cookie «user» (using the global variable $_COOKIE). We also use the isset() function to find out if the cookie is set:
<!DOCTYPE html>
<?php
$cookie_name = "user";
$cookie_value = "John Doe";
setcookie($cookie_name, $cookie_value, time() + (86400 * 30), "/"); // 86400 = 1 day
?>
<html>
<body>
<?php
if(!isset($_COOKIE[$cookie_name])) <
echo "Cookie named ‘" . $cookie_name . "’ is not set!";
> else <
echo "Cookie ‘" . $cookie_name . "’ is set!<br>";
echo "Value is: " . $_COOKIE[$cookie_name];
>
?>
Definition and Usage
The setcookie() function defines a cookie to be sent along with the rest of the HTTP headers.
A cookie is often used to identify a user. A cookie is a small file that the server embeds on the user’s computer. Each time the same computer requests a page with a browser, it will send the cookie too. With PHP, you can both create and retrieve cookie values.
The name of the cookie is automatically assigned to a variable of the same name. For example, if a cookie was sent with the name "user", a variable is automatically created called $user, containing the cookie value.
Note: The setcookie() function must appear BEFORE the <html> tag.
Note: The value of the cookie is automatically URLencoded when sending the cookie, and automatically decoded when received (to prevent URLencoding, use setrawcookie() instead).
Syntax
Parameter Values
| Parameter | Description |
|---|---|
| name | Required. Specifies the name of the cookie |
| value | Optional. Specifies the value of the cookie |
| expire | Optional. Specifies when the cookie expires. The value: time()+86400*30, will set the cookie to expire in 30 days. If this parameter is omitted or set to 0, the cookie will expire at the end of the session (when the browser closes). Default is 0 |
| path | Optional. Specifies the server path of the cookie. If set to "/", the cookie will be available within the entire domain. If set to "/php/", the cookie will only be available within the php directory and all sub-directories of php. The default value is the current directory that the cookie is being set in |
| domain | Optional. Specifies the domain name of the cookie. To make the cookie available on all subdomains of example.com, set domain to "example.com". Setting it to www.example.com will make the cookie only available in the www subdomain |
| secure | Optional. Specifies whether or not the cookie should only be transmitted over a secure HTTPS connection. TRUE indicates that the cookie will only be set if a secure connection exists. Default is FALSE |
| httponly | Optional. If set to TRUE the cookie will be accessible only through the HTTP protocol (the cookie will not be accessible by scripting languages). This setting can help to reduce identity theft through XSS attacks. Default is FALSE |
Technical Details
| Return Value: | TRUE on success. FALSE on failure |
|---|---|
| PHP Version: | 4+ |
| PHP Changelog: | PHP 5.5 — A Max-Age attribute was included in the Set-Cookie header sent to the client PHP 5.2 — The httponly parameter was added |
More Examples
Example
Several expire dates for cookies:
// cookie will expire when the browser close
setcookie("myCookie", $value);
// cookie will expire in 1 hour
setcookie("myCookie", $value, time() + 3600);
// cookie will expire in 1 hour, and will only be available
// within the php directory + all sub-directories of php
setcookie("myCookie", $value, time() + 3600, "/php/");
?>
<html>
<body>
Example
To modify a cookie, just set (again) the cookie using the setcookie() function:
<?php
if(!isset($_COOKIE[$cookie_name])) <
echo "Cookie named ‘" . $cookie_name . "’ is not set!";
> else <
echo "Cookie ‘" . $cookie_name . "’ is set!<br>";
echo "Value is: " . $_COOKIE[$cookie_name];
>
?>
Example
To delete a cookie, use the setcookie() function with an expiration date in the past:
Example
Create a small script that checks whether cookies are enabled. First, try to create a test cookie with the setcookie() function, then count the $_COOKIE array variable:
# Cookies
An HTTP cookie is a small piece of data sent from a website and stored on the user’s computer by the user’s web browser while the user is browsing.
# Modifying a Cookie
The value of a cookie can be modified by resetting the cookie
Cookies are part of the HTTP header, so setcookie() must be called before any output is sent to the browser.
When modifying a cookie make sure the path and domain parameters of setcookie() matches the existing cookie or a new cookie will be created instead.
The value portion of the cookie will automatically be urlencoded when you send the cookie, and when it is received, it is automatically decoded and assigned to a variable by the same name as the cookie name
# Setting a Cookie
A cookie is set using the setcookie() function. Since cookies are part of the HTTP header, you must set any cookies before sending any output to the browser.
- Creates a cookie with name user
- (Optional) Value of the cookie is Tom
- (Optional) Cookie will expire in 1 day (86400 seconds)
- (Optional) Cookie is available throughout the whole website /
- (Optional) Cookie is only sent over HTTPS
- (Optional) Cookie is not accessible to scripting languages such as JavaScript
A created or modified cookie can only be accessed on subsequent requests (where path and domain matches) as the superglobal $_COOKIE is not populated with the new data immediately.
# Checking if a Cookie is Set
Use the isset() function upon the superglobal $_COOKIE variable to check if a cookie is set.
# Removing a Cookie
To remove a cookie, set the expiry timestamp to a time in the past. This triggers the browser’s removal mechanism:
When deleting a cookie make sure the path and domain parameters of setcookie() matches the cookie you’re trying to delete or a new cookie, which expires immediately, will be created.
It is also a good idea to unset the $_COOKIE value in case the current page uses it:
# Retrieving a Cookie
Retrieve and Output a Cookie Named user
The value of a cookie can be retrieved using the global variable $_COOKIE . example if we have a cookie named user we can retrieve it like this
# Syntax
- bool setcookie( string $name [, string $value = "" [, int $expire = 0 [, string $path = "" [, string $domain = "" [, bool $secure = false [, bool $httponly = false ]]]]]] )
# Parameters
| parameter | detail |
|---|---|
| name | The name of the cookie. This is also the key you can use to retrieve the value from the $_COOKIE super global. This is the only required parameter |
| value | The value to store in the cookie. This data is accessible to the browser so don’t store anything sensitive here. |
| expire | A Unix timestamp representing when the cookie should expire. If set to zero the cookie will expire at the end of the session. If set to a number less than the current Unix timestamp the cookie will expire immediately. |
| path | The scope of the cookie. If set to / the cookie will be available within the entire domain. If set to /some-path/ then the cookie will only be available in that path and descendants of that path. Defaults to the current path of the file that the cookie is being set in. |
| domain | The domain or subdomain the cookie is available on. If set to the bare domain stackoverflow.com then the cookie will be available to that domain and all subdomains. If set to a subdomain meta.stackoverflow.com then the cookie will be available only on that subdomain, and all sub-subdomains. |
| secure | When set to TRUE the cookie will only be set if a secure HTTPS connection exists between the client and the server. |
| httponly | Specifies that the cookie should only be made available through the HTTP/S protocol and should not be available to client side scripting languages like JavaScript. Only available in PHP 5.2 or later. |
# Remarks
It is worth noting that mere invoking setcookie function doesn’t just put given data into $_COOKIE superglobal array.
For example there is no point in doing:
The value is not there yet, not until next page load. The function setcookie just says "with next http connection tell the client (browser) to set this cookie". Then when the headers are sent to the browser, they contain this cookie header. The browser then checks if the cookie hasn’t expired yet, and if not, then in http request it sends the cookie to the server and that’s when PHP receives it and puts the contents into $_COOKIE array.
setcookie
Альтернативная сигнатура доступна с PHP 7.3.0 (именованные параметры не поддерживаются):
setcookie() задаёт cookie, которое будет передано клиенту вместе с другими HTTP-заголовками. Как и любой другой заголовок, cookie должны передаваться до того как будут выведены какие-либо другие данные скрипта (это ограничение протокола). Это значит, что в скрипте вызовы этой функции должны располагаться до остального вывода, включая вывод тегов <html> и <head> , а также пустые строки и пробельные символы.
После передачи клиенту 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()
<?php
$value = ‘что-то откуда-то’ ;
setcookie ( «TestCookie» , $value );
setcookie ( «TestCookie» , $value , time ()+ 3600 ); /* срок действия 1 час */
setcookie ( «TestCookie» , $value , time ()+ 3600 , «/
Стоит отметить, что значение cookie перед отправкой клиенту подвергается URL-кодированию. При обратном получении значение cookie декодируется и помещается в переменную, с тем же именем, что и имя cookie. Если вы не хотите, чтобы значения кодировались, используйте функцию setrawcookie() . Посмотреть содержимое наших тестовых cookie можно, запустив один из следующих примеров:
<?php
// Вывести одно конкретное значение cookie
echo $_COOKIE [ «TestCookie» ];
// В целях тестирования и отладки может пригодиться вывод всех cookie
print_r ( $_COOKIE );
?>
Пример #2 Пример удаления cookie посредством setcookie()
Чтобы удалить cookie достаточно в качестве срока действия указать какое-либо время в прошлом. Это запустит механизм браузера, удаляющий истёкшие cookie. В примерах ниже показано, как удалить cookie, заданные в предыдущих примерах:
Пример #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» ;
>
>
?>
Результат выполнения данного примера:
Замечание: Использование разделительных символов, таких как [ и ] как часть имени файла 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() функции выполняются в том порядке, в котором вызывались.