Spec-Zone.ru › CodeIgniter 4

Куки

HTTP-куки (веб-куки, куки браузера) — небольшой фрагмент данных, который сервер отправляет веб-браузеру пользователя. Браузер может сохранить его и отправить обратно на тот же сервер при последующих запросах. Как правило, это используется для определения того, пришли ли два запроса от одного браузера — например, для поддержания входа пользователя в систему. Это запоминает состояние для бессостоятельного протокола HTTP.

Куки используются в основном для трёх целей:

  • Управление сеансом: Вход в систему, корзины покупок, результаты игр или всё, что сервер должен запомнить
  • Персонализация: Предпочтения пользователя, темы и другие настройки
  • Отслеживание: Запись и анализ поведения пользователя

Чтобы эффективно использовать куки в разных браузерах с вашим запросом и ответом, CodeIgniter предоставляет класс CodeIgniter\Cookie\Cookie, чтобы абстрагировать взаимодействие с куками.

  • Создание куки
  • Доступ к атрибутам куки
  • Неизменяемые куки
  • Проверка атрибутов куки
    • Проверка атрибута имени
    • Проверка атрибута префикса
    • Проверка атрибута SameSite
  • Использование хранилища куки
    • Проверка куки в хранилище
    • Получение куки из хранилища
    • Добавление/удаление куки из хранилища
    • Отправка куки из хранилища
  • Персонализация куки
  • Справочник по классу

Создание куки

В настоящее время существует четыре (4) способа создания нового объекта значения Cookie. 

use CodeIgniter\Cookie\Cookie;
use DateTime;

// Using the constructor
$cookie = new Cookie(
    'remember_token',
    'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
    [
        'expires'  => new DateTime('+2 hours'),
        'prefix'   => '__Secure-',
        'path'     => '/',
        'domain'   => '',
        'secure'   => true,
        'httponly' => true,
        'raw'      => false,
        'samesite' => Cookie::SAMESITE_LAX,
    ]
);

// Supplying a Set-Cookie header string
$cookie = Cookie::fromHeaderString(
    'remember_token=f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6; Path=/; Secure; HttpOnly; SameSite=Lax',
    false, // raw
);

// Using the fluent builder interface
$cookie = (new Cookie('remember_token'))
    ->withValue('f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6')
    ->withPrefix('__Secure-')
    ->withExpires(new DateTime('+2 hours'))
    ->withPath('/')
    ->withDomain('')
    ->withSecure(true)
    ->withHTTPOnly(true)
    ->withSameSite(Cookie::SAMESITE_LAX);

// Using the global function `cookie` which implicitly calls `new Cookie()`
$cookie = cookie('remember_token', 'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6');

При создании объекта Cookie, требуется только атрибут name. Все остальные — необязательны. Если необязательные атрибуты не изменены, их значения будут заполнены значениями по умолчанию, сохранёнными в классе Cookie. Чтобы переопределить значения по умолчанию, сохранённые в классе, можно передать экземпляр Config\Cookie или массив значений по умолчанию в статический метод Cookie::setDefaults().

use CodeIgniter\Cookie\Cookie;
use Config\Cookie as CookieConfig;

// pass in an Config\Cookie instance before constructing a Cookie class
Cookie::setDefaults(new CookieConfig());
$cookie = new Cookie('login_token');

// pass in an array of defaults
$myDefaults = [
    'expires'  => 0,
    'samesite' => Cookie::SAMESITE_STRICT,
];
Cookie::setDefaults($myDefaults);
$cookie = new Cookie('login_token');

Передача экземпляра Config\Cookie или массива методу Cookie::setDefaults() фактически перепишет значения по умолчанию и сохранит их до тех пор, пока не будут переданы новые значения по умолчанию. Если вы не хотите этого поведения, но хотите изменить значения по умолчанию на ограниченное время, вы можете воспользоваться возвращаемым значением метода Cookie::setDefaults(), которое возвращает старый массив значений по умолчанию.

use CodeIgniter\Cookie\Cookie;
use Config\Cookie as CookieConfig;

$oldDefaults = Cookie::setDefaults(new CookieConfig());
$cookie = new Cookie('my_token', 'muffins');

// return the old defaults
Cookie::setDefaults($oldDefaults);

Доступ к атрибутам куки

После создания вы можете легко получить доступ к атрибуту объекта Cookie с помощью одного из методов-геттеров.

use CodeIgniter\Cookie\Cookie;
use DateTime;
use DateTimeZone;

$cookie = new Cookie(
    'remember_token',
    'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
    [
        'expires'  => new DateTime('2025-02-14 00:00:00', new DateTimeZone('UTC')),
        'prefix'   => '__Secure-',
        'path'     => '/',
        'domain'   => '',
        'secure'   => true,
        'httponly' => true,
        'raw'      => false,
        'samesite' => Cookie::SAMESITE_LAX,
    ]
);

$cookie->getName(); // 'remember_token'
$cookie->getPrefix(); // '__Secure-'
$cookie->getPrefixedName(); // '__Secure-remember_token'
$cookie->getExpiresTimestamp(); // Unix timestamp
$cookie->getExpiresString(); // 'Fri, 14-Feb-2025 00:00:00 GMT'
$cookie->isExpired(); // false
$cookie->getMaxAge(); // the difference from time() to expires
$cookie->isRaw(); // false
$cookie->isSecure(); // true
$cookie->getPath(); // '/'
$cookie->getDomain(); // ''
$cookie->isHTTPOnly(); // true
$cookie->getSameSite(); // 'Lax'

// additional getter
$cookie->getId(); // '__Secure-remember_token;;/'

// when using `setcookie()`'s alternative signature on PHP 7.3+
// you can easily use the `getOptions()` method to supply the
// $options parameter
$cookie->getOptions();

Неизменяемые куки

Новый экземпляр Cookie — это неизменяемый объект-значение, представляющий HTTP-куки. Поскольку он неизменяемый, изменение любого из атрибутов экземпляра не повлияет на исходный экземпляр. Изменение всегда возвращает новый экземпляр. Вам нужно сохранить этот новый экземпляр, чтобы использовать его.

use CodeIgniter\Cookie\Cookie;

$cookie = new Cookie('login_token', 'admin');
$cookie->getName(); // 'login_token'

$cookie->withName('remember_token');
$cookie->getName(); // 'login_token'

$new = $cookie->withName('remember_token');
$new->getName(); // 'remember_token'

Проверка атрибутов куки

HTTP-куки регулируются несколькими спецификациями, которым необходимо следовать для их принятия браузерами. Таким образом, при создании или изменении определённых атрибутов Cookie, они проверяются, чтобы убедиться, что они соответствуют этим спецификациям.

Если были обнаружены нарушения, будет выброшено исключение CookieException.

Проверка атрибута имени

Имя куки может содержать любые символы US-ASCII, за исключением следующих:

  • управляющие символы;
  • пробелы или табуляции;
  • разделительные символы, такие как ( ) < > @ , ; : \ " / [ ] ? = { }

Если параметр $raw установлен в значение true, эта проверка будет строго выполнена. Это связано с тем, что PHP-функции setcookie и setrawcookie отклонят куки с недопустимыми именами. Кроме того, имя куки не может быть пустой строкой.

Проверка атрибута префикса

При использовании префикса __Secure- куки должны устанавливаться со флагом $secure в значении true. При использовании префикса __Host- куки должны соответствовать следующим требованиям:

  • флаг $secure должен быть установлен в значение true
  • $domain должно быть пустым
  • $path должно быть равно /

Проверка атрибута SameSite

Атрибут SameSite принимает только три (3) значения:

  • Lax: Куки не отправляются при обычных межсайтовых подзапросах (например, для загрузки изображений или фреймов на сторонний сайт), но отправляются, когда пользователь переходит на сайт-источник (т.е., при переходе по ссылке).
  • Strict: Куки будут отправляться только в контексте первого домена и не будут отправляться вместе с запросами, инициированными сторонними веб-сайтами.
  • None: Куки будут отправляться во всех контекстах, т.е., в ответах на запросы как первого домена, так и из другого источника.

Однако CodeIgniter позволяет установить атрибут SameSite в пустую строку. При использовании пустой строки будет использоваться значение SameSite по умолчанию, сохранённое в классе Cookie. Изменить значение SameSite по умолчанию можно с помощью метода Cookie::setDefaults(), как описано выше.

Недавние спецификации куки изменились, поэтому современные браузеры требуют установления значения SameSite по умолчанию, если оно не было указано. Это значение по умолчанию равно Lax. Если вы установили SameSite в пустую строку, а значение SameSite по умолчанию также пустое, вашему куки будет присвоено значение Lax.

Если SameSite установлено в None, необходимо убедиться, что Secure также установлено в true.

При записи атрибута SameSite класс Cookie принимает любое из значений, не чувствительно к регистру. Вы также можете воспользоваться константами класса, чтобы избежать проблем.

use CodeIgniter\Cookie\Cookie;

Cookie::SAMESITE_LAX; // 'lax'
Cookie::SAMESITE_STRICT; // 'strict'
Cookie::SAMESITE_NONE; // 'none'

Использование хранилища куки

Класс CookieStore представляет собой неизменяемую коллекцию объектов Cookie. Экземпляр CookieStore можно получить из текущего объекта Response.

use Config\Services;

$cookieStore = Services::response()->getCookieStore();

CodeIgniter предоставляет три (3) других способа создать новый экземпляр CookieStore.

use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;

// Passing an array of `Cookie` objects in the constructor
$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);

// Passing an array of `Set-Cookie` header strings
$store = CookieStore::fromCookieHeaders([
    'remember_token=me; Path=/; SameSite=Lax',
    'login_token=admin; Path=/; SameSite=Lax',
]);

// using the global `cookies` function
$store = cookies([new Cookie('login_token')], false);

// retrieving the `CookieStore` instance saved in our current `Response` object
$store = cookies();

Примечание

При использовании глобальной функции cookies(), переданный массив Cookie будет рассмотрен только в том случае, если второй аргумент, $getGlobal, установлен в значение false.

Проверка куки в хранилище

Чтобы проверить, существует ли объект Cookie в экземпляре CookieStore, можно использовать несколько способов:

use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;
use Config\Services;

// check if cookie is in the current cookie collection
$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);
$store->has('login_token');

// check if cookie is in the current Response's cookie collection
cookies()->has('login_token');
Services::response()->hasCookie('remember_token');

// using the cookie helper to check the current Response
// not available to v4.1.1 and lower
helper('cookie');
has_cookie('login_token');

Получение куки из хранилища

Получение экземпляра Cookie в коллекции куки очень просто:

use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;
use Config\Services;

// getting cookie in the current cookie collection
$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);
$store->get('login_token');

// getting cookie in the current Response's cookie collection
cookies()->get('login_token');
Services::response()->getCookie('remember_token');

// using the cookie helper to get cookie from the Response's cookie collection
helper('cookie');
get_cookie('remember_token');

Если имя недопустимо, при получении экземпляра Cookie непосредственно из объекта CookieStore будет выброшено исключение CookieException.

// throws CookieException
$store->get('unknown_cookie');

При получении экземпляра Cookie из коллекции куки текущего объекта Response, недопустимое имя просто вернёт null.

cookies()->get('unknown_cookie'); // null

Если при получении куки из объекта Response не указаны аргументы, будут отображены все объекты Cookie в хранилище.

cookies()->get(); // array of Cookie objects

// alternatively, you can use the display method
cookies()->display();

// or even from the Response
Services::response()->getCookies();

Примечание

Вспомогательная функция get_cookie() получает куки из текущего объекта Request, а не из Response. Эта функция проверяет массив $_COOKIE на наличие этой куки и извлекает её сразу же.

Добавление/удаление куки из хранилища

Как уже упоминалось, объекты CookieStore неизменяемы. Вам нужно сохранить изменённый экземпляр, чтобы работать с ним. Исходный экземпляр остаётся неизменным.

use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;
use Config\Services;

$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);

// adding a new Cookie instance
$new = $store->put(new Cookie('admin_token', 'yes'));

// removing a Cookie instance
$new = $store->remove('login_token');

Примечание

Удаление куки из хранилища НЕ удаляет её из браузера. Если вы хотите удалить куки из браузера, вы должны поместить в хранилище куки с пустым значением и тем же именем.

При взаимодействии с куками в хранилище текущего объекта Response можно безопасно добавлять или удалять куки, не беспокоясь об неизменяемости коллекции куки. Объект Response заменит экземпляр на изменённый экземпляр.

use Config\Services;

Services::response()->setCookie('admin_token', 'yes');
Services::response()->deleteCookie('login_token');

// using the cookie helper
helper('cookie');
set_cookie('admin_token', 'yes');
delete_cookie('login_token');

Отправка куки из хранилища

Чаще всего вам не нужно беспокоиться об отправке куки вручную. CodeIgniter сделает это за вас. Однако, если вам действительно нужно отправить куки вручную, вы можете использовать метод dispatch. Как и при отправке других заголовков, вы должны убедиться, что заголовки ещё не отправлены, проверив значение headers_sent().

use CodeIgniter\Cookie\Cookie;
use CodeIgniter\Cookie\CookieStore;

$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);

$store->dispatch(); // After dispatch, the collection is now empty.

Персонализация куки

В классе Cookie уже установлены разумные значения по умолчанию для обеспечения простого создания объектов куки. Однако вы можете настроить свои собственные настройки, изменив соответствующие настройки в классе Config\Cookie в файле app/Config/Cookie.php.

Настройка Варианты/Типы По умолчанию Описание
$prefix string '' Префикс, добавляемый к имени куки.
$expires DateTimeInterface|string|int 0 Маркер истечения срока действия куки.
$path string / Свойство пути куки.
$domain string '' Свойство домена куки. С конечной косой чертой.
$secure true/false false Требование HTTPS.
$httponly true/false true Недоступность для JavaScript.
$samesite Lax|None|Strict|lax|none|strict'' Lax Атрибут SameSite.
$raw true/false false Использование setrawcookie().

В ходе выполнения вы можете вручную установить новое значение по умолчанию, используя метод Cookie::setDefaults().

Справочник по классам

CodeIgniter\HTTP\Cookie\Cookie
static setDefaults([$config = []])
Параметры:
  • $config (ConfigCookie|array) – Массив конфигурации или экземпляр
Тип возвращаемого значения:

array<string, mixed>
Возвращаемое значение:

Старые значения по умолчанию

Устанавливает атрибуты по умолчанию для экземпляра Cookie, инжектируя значения из конфигурации \Config\Cookie или массива.

static fromHeaderString(string $header[, bool $raw = false])
Параметры:
  • $header (string) – Строка заголовка Set-Cookie
  • $raw (bool) – Флаг, указывающий, что данный куки не должен кодироваться по URL и отправляться через setrawcookie()
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

экземпляр Cookie
Исключения:

CookieException

Создаёт новый экземпляр Cookie из заголовка Set-Cookie.

__construct(string $name[, string $value = ''[, array $options = []]])
Параметры:
  • $name (string) – Имя куки
  • $value (string) – Значение куки
  • $options (array) – Параметры куки
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

экземпляр Cookie
Исключения:

CookieException

Конструирует новый экземпляр Cookie.

getId()
Тип возвращаемого значения: string
Возвращаемое значение: Идентификатор, используемый для индексирования в коллекции куки.
getPrefix(): string
getName(): string
getPrefixedName(): string
getValue(): string
getExpiresTimestamp(): int
getExpiresString(): string
isExpired(): bool
getMaxAge(): int
getDomain(): string
getPath(): string
isSecure(): bool
isHTTPOnly(): bool
getSameSite(): string
isRaw(): bool
getOptions(): array
withRaw([bool $raw = true])
Параметры:
  • $raw (bool) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с обновлённым параметром кодирования по URL.

withPrefix([string $prefix = ''])
Параметры:
  • $prefix (string) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с новым префиксом.

withName(string $name)
Параметры:
  • $name (string) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с новым именем.

withValue(string $value)
Параметры:
  • $value (string) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с новым значением.

withExpires($expires)
Параметры:
  • $expires (DateTimeInterface|string|int) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с новым временем истечения срока действия.

withExpired()
Тип возвращаемого значения: Cookie
Возвращаемое значение: новый экземпляр Cookie

Создаёт новый Cookie, который истечёт в браузере.

withNeverExpiring()
Параметры:
  • $name (string) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie, который практически никогда не истечёт.

withDomain(?string $domain)
Параметры:
  • $domain (string|null) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с новым доменом.

withPath(?string $path)
Параметры:
  • $path (string|null) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с новым путём.

withSecure([bool $secure = true])
Параметры:
  • $secure (bool) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с новым атрибутом «Secure».

withHTTPOnly([bool $httponly = true])
Параметры:
  • $httponly (bool) –
Тип возвращаемого значения:

Cookie
Возвращаемое значение:

новый экземпляр Cookie

Создаёт новый Cookie с новым атрибутом «HttpOnly».

withSameSite(string $samesite)
Параметры:
  • $samesite (строка) –
Тип возвращаемого значения:

Cookie
Возвращает:

новый экземпляр Cookie

Создаёт новый Cookie с новым атрибутом «SameSite».

toHeaderString()
Тип возвращаемого значения: строка
Возвращает: Возвращает строковое представление, которое может быть передано в качестве строки заголовка.
toArray()
Тип возвращаемого значения: массив
Возвращает: Возвращает массивное представление экземпляра Cookie.
CodeIgniter\HTTP\Cookie\CookieStore
static fromCookieHeaders(array $headers[, bool $raw = false])
Параметры:
  • $header (массив) – Массив заголовков Set-Cookie
  • $raw (bool) – Нужно ли использовать кодирование URL
Тип возвращаемого значения:

CookieStore
Возвращает:

экземпляр CookieStore
Исключения:

CookieException

Создаёт CookieStore из массива заголовков Set-Cookie.

__construct(array $cookies)
Параметры:
  • $cookies (массив) – Массив объектов Cookie
Тип возвращаемого значения:

CookieStore
Возвращает:

экземпляр CookieStore
Исключения:

CookieException
has(string $name[, string $prefix = ''[, ?string $value = null]]): bool
Параметры:
  • $name (строка) – Имя Cookie
  • $prefix (строка) – Префикс Cookie
  • $value (строка|null) – Значение Cookie
Тип возвращаемого значения:

bool
Возвращает:

Проверяет, присутствует ли объект Cookie с указанным именем и префиксом в коллекции.
get(string $name[, string $prefix = '']): Cookie
Параметры:
  • $name (строка) – Имя Cookie
  • $prefix (строка) – Префикс Cookie
Тип возвращаемого значения:

Cookie
Возвращает:

Возвращает экземпляр Cookie, идентифицированный по имени и префиксу.
Исключения:

CookieException
put(Cookie $cookie): CookieStore
Параметры:
  • $cookie (Cookie) – Объект Cookie
Тип возвращаемого значения:

CookieStore
Возвращает:

новый экземпляр CookieStore

Хранит новый cookie и возвращает новую коллекцию. Исходная коллекция остается неизменной.

remove(string $name[, string $prefix = '']): CookieStore
Параметры:
  • $name (строка) – Имя Cookie
  • $prefix (строка) – Префикс Cookie
Тип возвращаемого значения:

CookieStore
Возвращает:

новый экземпляр CookieStore

Удаляет cookie из коллекции и возвращает обновлённую коллекцию. Исходная коллекция остаётся неизменной.

dispatch(): void
Тип возвращаемого значения: void

Отправляет все cookies в хранилище.

display(): array
Тип возвращаемого значения: массив
Возвращает: Возвращает все экземпляры cookie в хранилище.
clear(): void
Тип возвращаемого значения: void

Очищает коллекцию cookies.

© 2014–2020 British Columbia Institute of Technology
Licensed under the MIT License.
https://codeigniter.com/user_guide/libraries/cookies.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API