Class CookieComponent

Cookie Component.

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

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

Namespace: Cake\Controller\Component
Link: http://book.cakephp.org/3.0/en/controllers/components/cookie.html

Property Summary

$_componentMap protected

array

A component lookup table used to lazy load component objects.
$_config protected

array

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_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.
$_registry protected

Cake\Controller\ComponentRegistry

Component registry class used to lazy load components.
$_response protected

Cake\Network\Response

A reference to the Controller's Cake\Network\Response object
$_validCiphers protected

array

Valid cipher names for encrypted cookies.
$_values protected

string

Values stored in the cookie.
$components public

array

Other Components this component uses.
$request public

Cake\Network\Request

Request object
$response public

Cake\Network\Response

Response object

Method Summary

__construct() public

Constructor
__debugInfo() public

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

Magic method for lazy loading $components.
_checkCipher() protected

Helper method for validating encryption cipher names.
_configDelete() protected

Delete a single config key
_configRead() protected

Read a config variable
_configWrite() protected

Write a config variable
_decode() protected

Decodes and decrypts a single value.
_decrypt() protected

Decrypts $value using public $type method in Security class
_delete() protected

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

Encrypts $value using public $type method in Security class
_explode() protected

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

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

Implode method to keep keys are multidimensional arrays
_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.
config() public

Usage
configKey() public

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

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

Delete a cookie value
implementedEvents() public

Events supported by this component.
initialize() public

Initialize config data and properties.
log() public

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

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

Write a value to the response cookies.

Method Detail

__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(): array

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

Returns

array

__get() ¶ public

__get(string $name): mixed

Magic method for lazy loading $components.

Parameters

string $name: Name of component to get.

Returns

mixed

A Component object or null.

_checkCipher() ¶ protected

_checkCipher(string $encrypt): void

Helper method for validating encryption cipher names.

Parameters

string $encrypt: The cipher name.

Returns

void

Throws

RuntimeException
When an invalid cipher is provided.

_configDelete() ¶ protected

_configDelete(string $key): void

Delete a single config key

Parameters

string $key: Key to delete.

Returns

void

Throws

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

_configRead() ¶ protected

_configRead(string|null $key): mixed

Read a config variable

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() ¶ protected

_configWrite(string|array $key, mixed $value, bool|string $merge = false): void

Write a config variable

Parameters

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

Returns

void

Throws

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

_decode() ¶ protected

_decode(string $value, string|false $encrypt): string

Decodes and decrypts a single value.

Parameters

string $value: The value to decode & decrypt.
string|false $encrypt: The encryption cipher to use.

Returns

string

Decoded value.

_decrypt() ¶ protected

_decrypt(array $values, string|bool $mode): string

Decrypts $value using public $type method in Security class

Parameters

array $values: Values to decrypt
string|bool $mode: Encryption mode

Returns

string

decrypted string

_delete() ¶ protected

_delete(string $name): void

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

Returns

void

_encrypt() ¶ protected

_encrypt(string $value, string|bool $encrypt, string|null $key = null): string

Encrypts $value using public $type method in Security class

Parameters

string $value: Value to encrypt
string|bool $encrypt: Encryption mode to use. False disabled encryption.
string|null $key optional: Used as the security salt only in this time for tests if specified.

Returns

string

Encoded values

_explode() ¶ protected

_explode(string $string): array

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

array

Map of key and values

_getCookieEncryptionKey() ¶ protected

_getCookieEncryptionKey(): string

Returns the encryption key to be used.

Returns

string

_implode() ¶ protected

_implode(array $array): string

Implode method to keep keys are multidimensional arrays

Parameters

array $array: Map of key and values

Returns

string

A json encoded string.

_load() ¶ protected

_load(string|array $key): void

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.

Returns

void

_write() ¶ protected

_write(string $name, string $value): void

Set cookie

Parameters

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

Returns

void

check() ¶ public

check(string|null $key = null): bool

Returns true if given key is set in the cookie.

Parameters

string|null $key optional: Key to check for

Returns

bool

True if the key exists

config() ¶ public

config(string|array|null $key = null, mixed|null $value = null, bool $merge = true): mixed

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: The key to get/set, or a complete array of configs.
mixed|null $value optional: The value to set.
bool $merge optional: 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.

configKey() ¶ public

configKey(string $keyname, null|string|array $option = null, string|null $value = null): array|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: 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: Either the value to set, or empty when $option is an array.

Returns

array|null

configShallow() ¶ public

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

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->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 $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

The object itself.

delete() ¶ public

delete(string $key): void

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

Returns

void

implementedEvents() ¶ public

implementedEvents(): array

Events supported by this component.

Uses Conventions to map controller events to standard component callback method names. By defining one of the callback methods a component is assumed to be interested in the related event.

Override this method if you need to add non-conventional event listeners. Or if you want components to listen to non-standard events.

Returns

array

initialize() ¶ public

initialize(array $config): void

Initialize config data and properties.

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

array $config: The config data.

Returns

void

log() ¶ public

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

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

Parameters

mixed $msg: Log message.
int|string $level optional: Error level.
string|array $context optional: Additional log data relevant to this message.

Returns

bool

Success of log write.

read() ¶ public

read(string|null $key = null): string

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: Key of the value to be obtained.

Returns

string

or null, value for specified key

write() ¶ public

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

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: Value

Returns

void

Property Detail

`$_componentMap` ¶ protected

A component lookup table used to lazy load component objects.

Type

array

`$_config` ¶ protected

Runtime config

Type

array

`$_configInitialized` ¶ protected

Whether the config property has already been configured with defaults

Type

bool

`$_defaultConfig` ¶ protected

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'.

Type

array

`$_keyConfig` ¶ protected

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.

Type

array

`$_loaded` ¶ protected

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.

Type

array

`$_registry` ¶ protected

Component registry class used to lazy load components.

Type

Cake\Controller\ComponentRegistry

`$_response` ¶ protected

A reference to the Controller's Cake\Network\Response object

Type

Cake\Network\Response

`$_validCiphers` ¶ protected

Valid cipher names for encrypted cookies.

Type

array

`$_values` ¶ protected

Values stored in the cookie.

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

Type

string

`$components` ¶ public

Other Components this component uses.

Type

array

`$request` ¶ public

Request object

Type

Cake\Network\Request

`$response` ¶ public

Response object

Type

Cake\Network\Response

Namespaces

Class CookieComponent

Property Summary

Method Summary

__construct() public

__debugInfo() public

__get() public

_checkCipher() protected

_configDelete() protected

_configRead() protected

_configWrite() protected

_decode() protected

_decrypt() protected

_delete() protected

_encrypt() protected

_explode() protected

_getCookieEncryptionKey() protected

_implode() protected

_load() protected

_write() protected

check() public

config() public

Usage

configKey() public

configShallow() public

delete() public

implementedEvents() public

initialize() public

log() public

read() public

write() public

Method Detail

__construct() ¶ public

Parameters

__debugInfo() ¶ public

Returns

__get() ¶ public

Parameters

Returns

_checkCipher() ¶ protected

Parameters

Returns

Throws

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_decode() ¶ protected

Parameters

Returns

_decrypt() ¶ protected

Parameters

Returns

_delete() ¶ protected

Parameters

Returns

_encrypt() ¶ protected

Parameters

Returns

_explode() ¶ protected

Parameters

Returns

_getCookieEncryptionKey() ¶ protected

Returns

_implode() ¶ protected

Parameters

Returns

_load() ¶ protected

Parameters

Returns

_write() ¶ protected

Parameters

Returns

`$_componentMap` ¶ protected

`$_config` ¶ protected

`$_configInitialized` ¶ protected

`$_defaultConfig` ¶ protected

`$_keyConfig` ¶ protected

`$_loaded` ¶ protected

`$_registry` ¶ protected

`$_response` ¶ protected

`$_validCiphers` ¶ protected

`$_values` ¶ protected

`$components` ¶ public

`$request` ¶ public

`$response` ¶ public