Class CookieComponent

Cookie Component.

Provides enhanced cookie handling features for use in the controller layer. In addition to the basic features offered be Cake\Http\Response, this class lets you:

Create and read encrypted cookies.
Store non-scalar data.
Use hash compatible syntax to read/write/delete values.

Cake\Controller\Component implements Cake\Event\EventListenerInterface uses Cake\Core\InstanceConfigTrait , Cake\Log\LogTrait

Cake\Controller\Component\CookieComponent uses Cake\Utility\CookieCryptTrait

Namespace: Cake\Controller\Component
Link: https://book.cakephp.org/3.0/en/controllers/components/cookie.html
Deprecated: 3.5.0 Use Cake\Http\Middleware\EncryptedCookieMiddleware and Cake\Http\Cookie\Cookie methods instead.
Location: Controller/Component/CookieComponent.php

Properties summary

$_defaultConfig protected

array

Default config
$_keyConfig protected

array

Config specific to a given top level key name.
$_loaded protected

array

A map of keys that have been loaded.
$_response protected

Cake\Http\Response|null

A reference to the Controller's Cake\Http\Response object. Currently unused.
$_values protected

array

Values stored in the cookie.

Inherited Properties

_componentMap, _registry, components, request, response _config, _configInitialized _validCiphers

Method Summary

_delete() protected

Sets a cookie expire time to remove cookie value.
_getCookieEncryptionKey() protected

Returns the encryption key to be used.
_load() protected

Load the cookie data from the request and response objects.
_write() protected

Set cookie
check() public

Returns true if given key is set in the cookie.
configKey() public

Set the configuration for a specific top level key.
delete() public

Delete a cookie value
implementedEvents() public

Events supported by this component.
initialize() public

Initialize config data and properties.
read() public

Read the value of key path from request cookies.
write() public

Write a value to the response cookies.

Method Detail

_delete() protected ¶

_delete( string $name )

Sets a cookie expire time to remove cookie value.

This is only done once all values in a cookie key have been removed with delete.

Parameters

string $name: Name of cookie

_getCookieEncryptionKey() protected ¶

_getCookieEncryptionKey( )

Returns the encryption key to be used.

Returns

string

_load() protected ¶

_load( string|array $key )

Load the cookie data from the request and response objects.

Based on the configuration data, cookies will be decrypted. When cookies contain array data, that data will be expanded.

Parameters

string|array $key: The key to load.

_write() protected ¶

_write( string $name , string $value )

Set cookie

Parameters

string $name: Name for cookie
string $value: Value for cookie

check() public ¶

check( string|null $key null )

Returns true if given key is set in the cookie.

Parameters

string|null $key optional null: Key to check for

Returns

boolean
True if the key exists

configKey() public ¶

configKey( string $keyname , null|string|array $option null , string|null $value null )

Set the configuration for a specific top level key.

Examples:

Set a single config option for a key:

$this->Cookie->configKey('User', 'expires', '+3 months');

Set multiple options:

$this->Cookie->configKey('User', [
  'expires', '+3 months',
  'httpOnly' => true,
]);

Parameters

string $keyname: The top level keyname to configure.
null|string|array $option optional null: Either the option name to set, or an array of options to set, or null to read config options for a given key.
string|null $value optional null: Either the value to set, or empty when $option is an array.

Returns

array|null

delete() public ¶

delete( string $key )

Delete a cookie value

You must use this method before any output is sent to the browser. Failure to do so will result in header already sent errors.

Deleting a top level key will delete all keys nested within that key. For example deleting the User key, will also delete User.email.

Parameters

string $key: Key of the value to be deleted

implementedEvents() public ¶

implementedEvents( )

Events supported by this component.

Returns

array

Overrides

Cake\Controller\Component::implementedEvents()

initialize() public ¶

initialize( array $config )

Initialize config data and properties.

Parameters

array $config: The config data.

Overrides

Cake\Controller\Component::initialize()

read() public ¶

read( string|null $key null )

Read the value of key path from request cookies.

This method will also allow you to read cookies that have been written in this request, but not yet sent to the client.

Parameters

string|null $key optional null: Key of the value to be obtained.

Returns

string
or null, value for specified key

write() public ¶

write( string|array $key , mixed $value null )

Write a value to the response cookies.

You must use this method before any output is sent to the browser. Failure to do so will result in header already sent errors.

Parameters

string|array $key: Key for the value
mixed $value optional null: Value

Methods inherited from Cake\Controller\Component

__construct() public ¶

__construct( Cake\Controller\ComponentRegistry $registry , array $config [] )

Constructor

Parameters

Cake\Controller\ComponentRegistry $registry: A ComponentRegistry this component can use to lazy load its components
array $config optional []: Array of configuration settings.

__debugInfo() public ¶

__debugInfo( )

Returns an array that can be used to describe the internal state of this object.

Returns

array

__get() public ¶

__get( string $name )

Magic method for lazy loading $components.

Parameters

string $name: Name of component to get.

Returns

mixed
A Component object or null.

getController() public ¶

getController( )

Get the controller this component is bound to.

Returns

Cake\Controller\Controller
The bound controller.

Methods used from Cake\Utility\CookieCryptTrait

_checkCipher() protected ¶

_checkCipher( string $encrypt )

Helper method for validating encryption cipher names.

Parameters

string $encrypt: The cipher name.

Throws

RuntimeException
When an invalid cipher is provided.

_decode() protected ¶

_decode( string $value , string|false $encrypt , string|null $key )

Decodes and decrypts a single value.

Parameters

string $value: The value to decode & decrypt.
string|false $encrypt: The encryption cipher to use.
string|null $key: Used as the security salt if specified.

Returns

string|array
Decoded values.

_decrypt() protected ¶

_decrypt( array $values , string|boolean $mode , string|null $key null )

Decrypts $value using public $type method in Security class

Parameters

array $values: Values to decrypt
string|boolean $mode: Encryption mode
string|null $key optional null: Used as the security salt if specified.

Returns

string|array
Decrypted values

_encrypt() protected ¶

_encrypt( string $value , string|boolean $encrypt , string|null $key null )

Encrypts $value using public $type method in Security class

Parameters

string $value: Value to encrypt
string|boolean $encrypt: Encryption mode to use. False disabled encryption.
string|null $key optional null: Used as the security salt if specified.

Returns

string
Encoded values

_explode() protected ¶

_explode( string $string )

Explode method to return array from string set in CookieComponent::_implode() Maintains reading backwards compatibility with 1.x CookieComponent::_implode().

Parameters

string $string: A string containing JSON encoded data, or a bare string.

Returns

string|array
Map of key and values

_implode() protected ¶

_implode( array $array )

Implode method to keep keys are multidimensional arrays

Parameters

array $array: Map of key and values

Returns

string
A json encoded string.

Methods used from Cake\Core\InstanceConfigTrait

_configDelete() protected ¶

_configDelete( string $key )

Deletes a single config key.

Parameters

string $key: Key to delete.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() protected ¶

_configRead( string|null $key )

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() protected ¶

_configWrite( string|array $key , mixed $value , boolean|string $merge false )

Writes a config key.

Parameters

string|array $key: Key to write to.
mixed $value: Value to write.
boolean|string $merge optional false: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

config() public ¶

config( string|array|null $key null , mixed|null $value null , boolean $merge true )

Gets/Sets the config.

Usage

Reading the whole config:

$this->config();

Reading a specific value:

$this->config('key');

Reading a nested value:

$this->config('some.nested.key');

Setting a specific value:

$this->config('key', $value);

Setting a nested value:

$this->config('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->config(['one' => 'value', 'another' => 'value']);

Parameters

string|array|null $key optional null: The key to get/set, or a complete array of configs.
mixed|null $value optional null: The value to set.
boolean $merge optional true: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

mixed
Config value being read, or the object itself on write operations.

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

configShallow() public ¶

configShallow( string|array $key , mixed|null $value null )

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key: The key to set, or a complete array of configs.
mixed|null $value optional null: The value to set.

Returns

$this

getConfig() public ¶

getConfig( string|null $key null , mixed $default null )

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional null: The key to get or null for the whole config.
mixed $default optional null: The return value when the key does not exist.

Returns

mixed
Config value being read.

setConfig() public ¶

setConfig( string|array $key , mixed|null $value null , boolean $merge true )

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key: The key to set, or a complete array of configs.
mixed|null $value optional null: The value to set.
boolean $merge optional true: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

Methods used from Cake\Log\LogTrait

log() public ¶

log( mixed $msg , integer|string $level LogLevel::ERROR , string|array $context [] )

Convenience method to write a message to Log. See Log::write() for more information on writing to logs.

Parameters

mixed $msg: Log message.
integer|string $level optional LogLevel::ERROR: Error level.
string|array $context optional []: Additional log data relevant to this message.

Returns

boolean
Success of log write.

Properties detail

`$_defaultConfig` ¶

protected array

Default config

expires - How long the cookies should last for. Defaults to 1 month.
path - The path on the server in which the cookie will be available on. If path is set to '/foo/', the cookie will only be available within the /foo/ directory and all sub-directories such as /foo/bar/ of domain. The default value is base path of app. For e.g. if your app is running under a subfolder "cakeapp" of document root the path would be "/cakeapp/" else it would be "/".
domain - The domain that the cookie is available. To make the cookie available on all subdomains of example.com set domain to '.example.com'.
secure - Indicates that the cookie should only be transmitted over a secure HTTPS connection. When set to true, the cookie will only be set if a secure connection exists.
key - Encryption key used when encrypted cookies are enabled. Defaults to Security.salt.
httpOnly - Set to true to make HTTP only cookies. Cookies that are HTTP only are not accessible in JavaScript. Default false.
encryption - Type of encryption to use. Defaults to 'aes'.

[
    'path' => null,
    'domain' => '',
    'secure' => false,
    'key' => null,
    'httpOnly' => false,
    'encryption' => 'aes',
    'expires' => '+1 month',
]

`$_keyConfig` ¶

protected array

Config specific to a given top level key name.

The values in this array are merged with the general config to generate the configuration for a given top level cookie name.

[]

`$_loaded` ¶

protected array

A map of keys that have been loaded.

Since CookieComponent lazily reads cookie data, we need to track which cookies have been read to account for read, delete, read patterns.

[]

`$_response` ¶

protected Cake\Http\Response|null

A reference to the Controller's Cake\Http\Response object. Currently unused.

Deprecated

3.4.0 Will be removed in 4.0.0

`$_values` ¶

protected array

Values stored in the cookie.

Accessed in the controller using $this->Cookie->read('Name.key');

[]

Namespaces

Classes

Class CookieComponent

Properties summary

Inherited Properties

Method Summary

_delete() protected

_getCookieEncryptionKey() protected

_load() protected

_write() protected

check() public

configKey() public

delete() public

implementedEvents() public

initialize() public

read() public

write() public

Method Detail

_delete() protected ¶

Parameters

_getCookieEncryptionKey() protected ¶

Returns

_load() protected ¶

Parameters

_write() protected ¶

Parameters

check() public ¶

Parameters

Returns

configKey() public ¶

Examples:

Parameters

Returns

delete() public ¶

Parameters

implementedEvents() public ¶

Returns

Overrides

initialize() public ¶

Parameters

Overrides

read() public ¶

Parameters

Returns

write() public ¶

Parameters

Methods inherited from Cake\Controller\Component

__construct() public ¶

Parameters

__debugInfo() public ¶

Returns

__get() public ¶

Parameters

Returns

getController() public ¶

Returns

Methods used from Cake\Utility\CookieCryptTrait

_checkCipher() protected ¶

Parameters

Throws

_decode() protected ¶

Parameters

Returns

_decrypt() protected ¶

Parameters

Returns

_encrypt() protected ¶

Parameters

Returns

_explode() protected ¶

Parameters

Returns

_implode() protected ¶

Parameters

Returns

Methods used from Cake\Core\InstanceConfigTrait

_configDelete() protected ¶

Parameters

Throws

_configRead() protected ¶

`$_defaultConfig` ¶

`$_keyConfig` ¶

`$_loaded` ¶

`$_response` ¶

`$_values` ¶