« pfsockopensetrawcookie »PHP ManualМережеві функції

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, яке буде надіслано клієнту разом з іншими заголовками HTTP. Як і інші заголовки файл cookie повинен передаватися до того, як буде виведено будь-які інші дані скрипту (це обмеження протоколу). Для цього потрібно викликати функцію до іншого висновку, включаючи виведення тегів <html>и<head>, а також порожні рядки та символи пробілів.

После установки cookie к нему можно будет получить доступ через суперглобальную переменную$_COOKIE при наступному завантаженні сторінки. Значення cookie також може містити суперглобальна змінна $_REQUEST

Список параметрів

Стандарт» RFC 6265 дає конкретні вказівки у тому, як потрібно інтерпретувати кожен із параметрів setcookie()

name

Назву cookie.

value

Значення cookie. Це значення буде збережено на клієнтському комп'ютері; не записуйте секретні дані в cookie. Значення, присвоєне cookie з ім'ям name, допустим,'cookiename', будет доступно через$_COOKIE['cookiename']

expires_or_options

Час закінчення терміну дії cookie. Це позначка часу Unix, тобто кількість секунд від початку епохи. Один із способів встановлення значення – додати кількість секунд до закінчення терміну дії cookie до результату виклику функції time(). Наприклад, вираз time() + 60 * 60 * 24 * 30 встановить термін дії cookie, який закінчиться за 30 днів. Інший варіант – викликати функцію mktime(). Якщо поставити або пропустити аргумент, термін дії 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()****

Loading...

Варто зазначити, що значення cookie перед надсиланням клієнту піддається URL-коду. При зворотному отриманні значення cookie декодується і поміщається в змінну, з тим самим ім'ям, що ім'я cookie. Якщо ви не бажаєте, щоб значення кодувалися, використовуйте функцію setrawcookie(). Подивитися вміст наших тестових cookie можна, запустивши один із таких прикладів:

Loading...

Приклад #2 Приклад удаления cookie посредствомsetcookie()****

Щоб видалити cookie, достатньо як термін дії вказати якийсь час у минулому. Це запустить механізм браузера, що видаляє cookie, що минув. У нижченаведених прикладах показано, як видалити cookie, задані в попередніх прикладах:

Loading...

Приклад #3setcookie()** та масиви**

Є можливість розміщувати в cookie масиви. Для цього кожному cookie потрібно дати ім'я відповідно до правил іменування масивів. Така можливість дозволяє помістити стільки значень, скільки є елементів у масиві. При зворотному отриманні всі ці значення будуть поміщені в масив з ім'ям цього cookie:

Loading...

Результат виконання наведеного прикладу:

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 задають у параметріexpires_or_options. Хороший спосіб налагодити наявність файлів cookie - просто викликати функціюprint_r($_COOKIE);
  • При видаленні cookie повинні бути задані самі параметри, що і при установці. Якщо в якості значення встановити пустий рядок, а інші параметри відповідають попередньому виклику функції setcookie, то cookie з заданим ім'ям буде видалено на віддаленому клієнті. Внутрішньо це виглядає так: cookie буде надано значення«deleted», а термін дії переноситься на рік у минуле.
  • Оскільки встановлення значення**falseпризведе до видалення cookie, не потрібно задавати cookie логічні значення. Натомість можна вказати дляfalseи дляtrue**
  • Імена cookie дозволено встановлювати масивом імен, які будуть доступні в PHP-скрипті як масиви, але в системі користувача вони зберігатимуться у вигляді окремих записів. Для завдання cookie з кількома іменами та значеннями рекомендовано викликати функціюexplode(). Не рекомендовано користуватися для цього функцієюserialize()оскільки це порушує безпеку.

Численні виклики функції setcookie() виконуються у порядку дзвінка.

Дивіться також