Функция PHP setrawcookie(): всё, что нужно знать

Как PHP-разработчик, вам может потребоваться устанавливать «сырые» куки для вашего веб-приложения, чтобы хранить информацию на стороне клиента. Функция setrawcookie() — это встроенная PHP-функция, позволяющая установить куки без кодирования значения. В отличие от стандартной функции setcookie(), функция setrawcookie() не выполняет URL-кодирование значения куки, что делает её полезной при необходимости хранить предварительно закодированные данные или бинарные строки. В этой статье мы подробно рассмотрим функцию setrawcookie() — её синтаксис, параметры, современную форму с массивом опций, распространённые подводные камни и отличия от setcookie().

На этой странице предполагается, что вы уже понимаете основы куков в PHP. Если вам нужно просто сохранить обычный текст, setcookie() обычно является лучшим выбором — используйте setrawcookie() только тогда, когда необходимо передать значение в точности как есть.

Что такое функция setrawcookie()?

Функция setrawcookie() — это встроенная PHP-функция (доступна начиная с PHP 5.2.0), позволяющая установить «сырые» куки на стороне клиента. Она работает, добавляя HTTP-заголовок ответа Set-Cookie, поэтому — как и любая функция, отправляющая заголовки — она должна быть вызвана до отправки какого-либо вывода в браузер (нет выведенного HTML, нет пустых строк перед <?php, нет BOM). Если вывод уже начался, заголовок будет молча проигнорирован. Для обнаружения этой ситуации используйте headers_sent().

Функция возвращает true, если заголовок был успешно поставлен в очередь, и false при ошибке. Обратите внимание, что возврат true не гарантирует, что браузер принял или вернёт куки — это означает лишь то, что заголовок был отправлен.

Как использовать функцию setrawcookie()

Использование функции setrawcookie() довольно простое. Вот синтаксис:

Синтаксис PHP

setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

Функция принимает семь параметров:

$name: Имя куки.
$value: Необработанное значение куки (без URL-кодирования).
$expire: Время истечения срока действия в виде Unix-временной метки.
$path: Путь на сервере, по которому куки будет доступна.
$domain: Домен, на котором куки будет доступна.
$secure: Должна ли куки передаваться только по HTTPS.
$httponly: Должна ли куки быть недоступна для JavaScript на стороне клиента.

Вот пример использования функции setrawcookie() для установки «сырой» куки:

Пример

<?php

$name = "username";
$value = "john";
$expire = time() + (86400 * 30); // 30 days
$path = "/";
$domain = ".example.com";
$secure = true;
$httponly = true;
setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

В этом примере мы используем функцию setrawcookie() для установки «сырой» куки с именем username и значением john. Мы указываем срок действия 30 дней с текущего момента (используя time() в качестве базы), путь на сервере / и домен .example.com. Флаги secure и httponly установлены в true, чтобы куки передавалась только по HTTPS и была недоступна для JavaScript на стороне клиента.

Форма с массивом опций (PHP 7.3+)

Начиная с PHP 7.3 можно передать один массив $options вместо позиционных аргументов. Это рекомендуемая форма, поскольку она является единственным способом установить атрибут SameSite, контролирующий отправку куки при межсайтовых запросах:

<?php

setrawcookie("username", "john", [
    "expires"  => time() + (86400 * 30), // 30 days
    "path"     => "/",
    "domain"   => ".example.com",
    "secure"   => true,
    "httponly" => true,
    "samesite" => "Strict", // "Strict", "Lax", or "None"
]);

При использовании формы с массивом ключ $expire называется expires (с буквой s), а samesite не имеет эквивалента в позиционной сигнатуре.

Чтение куки

Куки, установленная в одном запросе, недоступна в $_COOKIE до тех пор, пока браузер не вернёт её в следующем запросе. В последующем запросе её можно прочитать как любую другую куки:

<?php

if (isset($_COOKIE["username"])) {
    echo "Welcome back, " . $_COOKIE["username"];
} else {
    echo "Cookie not set yet.";
}

Поскольку setrawcookie() не кодирует значение, сохранённые байты возвращаются в точности как есть — шаг автоматического urldecode() при чтении отсутствует.

Удаление «сырой» куки

Чтобы удалить куки, установите её повторно с временем истечения в прошлом. Параметры name, path и domain должны совпадать с исходными:

<?php

setrawcookie("username", "", time() - 3600, "/", ".example.com");

setrawcookie() и setcookie()

Главное различие между setcookie() и setrawcookie() заключается в обработке значения куки. Функция setcookie() автоматически выполняет URL-кодирование значения с помощью rawurlencode(), что безопасно для стандартного текста, но может вызвать проблемы, если нужно хранить предварительно закодированные данные или бинарные строки. Функция setrawcookie() пропускает этот шаг кодирования, предоставляя полный контроль над необработанным значением. Для большинства стандартных случаев предпочтительна setcookie(), однако setrawcookie() незаменима при работе с уже закодированными данными.

Практическое следствие: при использовании setrawcookie() вы несёте ответственность за безопасность значения куки. Необработанное значение куки не должно содержать определённые символы — управляющие символы, пробелы, запятые, точки с запятой или знаки равенства — поскольку они имеют специальное значение в заголовке Set-Cookie. Если ваше значение может содержать такие символы, закодируйте его самостоятельно (например, с помощью rawurlencode()) перед передачей:

<?php

$raw = rawurlencode("john doe; admin=1"); // pre-encode unsafe bytes
setrawcookie("username", $raw, time() + 3600, "/");

Аспект	`setcookie()`	`setrawcookie()`
URL-кодирует значение	Да (`rawurlencode()`)	Нет
Подходит для обычного текста	Да	Работает, но без преимуществ
Подходит для предварительно закодированных / бинарных данных	Нет (двойное кодирование)	Да
Те же параметры и массив опций	Да	Да

Заключение

Функция setrawcookie() — это полезный инструмент для установки «сырых» куков в вашем PHP веб-приложении. Понимая её синтаксис, параметры, форму с массивом опций и отличия от setcookie(), вы сможете безопасно хранить предварительно закодированные данные на стороне клиента. Не забывайте вызывать её до любого вывода, предпочитайте массив опций для возможности установить SameSite, и используйте её только тогда, когда действительно нужно обойти URL-кодирование.

Связанные темы

Куки в PHP — общая картина работы куков в PHP.
setcookie() — стандартная функция установки куков с URL-кодированием.
Сессии PHP — состояние на стороне сервера, альтернатива кукам.
header() — отправка произвольных HTTP-заголовков вручную.
headers_sent() — проверка того, были ли уже отправлены заголовки.

Practice

Практика

Каков правильный способ использования функции setrawcookie() в PHP?

setrawcookie(name, value, expire)setrawcookie(name, value, expire, path, domain, secure, httponly)setrawcookie(name, value)setrawcookie(name, value, expire, path, domain, secure, httponly, options)setrawcookie(name, value, expire, path, domain, secure)