Cookies

An HTTP cookie (web cookie, browser cookie) is a small piece of data that a server sends to the user’s web browser. The browser may store it and send it back with later requests to the same server. Typically, it’s used to tell if two requests came from the same browser - keeping a user logged-in, for example. It remembers stateful information for the stateless HTTP protocol.

Cookies are mainly used for three purposes:

Session management: Logins, shopping carts, game scores, or anything else the server should remember
Personalization: User preferences, themes, and other settings
Tracking: Recording and analyzing user behavior

To help you efficiently send cookies to browsers, CodeIgniter provides the CodeIgniter\Cookie\Cookie class to abstract the cookie interaction.

Creating Cookies
- Overriding Defaults
Accessing Cookie’s Attributes
Immutable Cookies
Validating a Cookie’s Attributes
Sending Cookies
Using the Cookie Store
Cookie Personalization
Class Reference

Creating Cookies 

There are currently four (4) ways to create a new Cookie value object.

<?php

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');

When constructing the Cookie object, only the name attribute is required. All other else are optional. If the optional attributes are not modified, their values will be filled up by the default values saved in the Cookie class.

Overriding Defaults 

To override the defaults currently stored in the class, you can pass a Config\Cookie instance or an array of defaults to the static Cookie::setDefaults() method.

<?php

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

// pass in a 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');

Passing the Config\Cookie instance or an array to Cookie::setDefaults() will effectively overwrite your defaults and will persist until new defaults are passed.

Changing Defaults for a Limited Time

If you do not want this behavior but only want to change defaults for a limited time, you can take advantage of Cookie::setDefaults() return which returns the old defaults array.

<?php

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);

Immutable Cookies 

A new Cookie instance is an immutable value object representation of an HTTP cookie. Being immutable, modifying any of the instance’s attributes will not affect the original instance. The modification always returns a new instance. You need to retain this new instance in order to use it.

<?php

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'

Sending Cookies 

Set the Cookie objects in the CookieStore of the Response object, and the framework will automatically send the cookies.

Use CodeIgniter\HTTP\Response::setCookie() to set:

<?php

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

$response = Services::response();

$cookie = new Cookie(
    'remember_token',
    'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
    [
        'max-age' => 3600 * 2, // Expires in 2 hours
    ]
);

$response->setCookie($cookie);

You can also use the set_cookie() helper function:

<?php

use CodeIgniter\Cookie\Cookie;

helper('cookie');

$cookie = new Cookie(
    'remember_token',
    'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
    [
        'max-age' => 3600 * 2, // Expires in 2 hours
    ]
);

set_cookie($cookie);

Cookie Personalization 

Sane defaults are already in place inside the Cookie class to ensure the smooth creation of cookie objects. However, you may wish to define your own settings by changing the following settings in the Config\Cookie class in app/Config/Cookie.php file.

Setting	Options/ Types	Default	Description
$prefix	`string`	`''`	Prefix to prepend to the cookie name.
$expires	`DateTimeInterface\|string\|int`	`0`	The expires timestamp.
$path	`string`	`/`	The path property of the cookie.
$domain	`string`	`''`	The domain property of the cookie.with trailing slash.
$secure	`true/false`	`false`	If to be sent over secure HTTPS.
$httponly	`true/false`	`true`	If not accessible to JavaScript.
$samesite	`Lax\|None\|Strict\|lax\|none\|strict''`	`Lax`	The SameSite attribute.
$raw	`true/false`	`false`	If to be dispatched using `setrawcookie()`.

In runtime, you can manually supply a new default using the Cookie::setDefaults() method.