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.
Properties 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\Http\Response|null
A reference to the Controller's Cake\Http\Response object.
- $_validCiphers protected
string[]
Valid cipher names for encrypted cookies.
- $_values protected
array
Values stored in the cookie.
- $components public
array
Other Components this component uses.
- $request public
\Cake\Http\ServerRequest
Request object
- $response public
\Cake\Http\Response
Response object
Method Summary
- __debugInfo() public
Returns an array that can be used to describe the internal state of this object.
- _explode() protected
Explode method to return array from string set in CookieComponent::_implode() Maintains reading backwards compatibility with 1.x CookieComponent::_implode().
- configShallow() public
Merge provided config with existing config. Unlike
config()
which does a recursive merge for nested keys, this method does a simple merge. - log() public
Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
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()
Returns an array that can be used to describe the internal state of this object.
Returns
array
__get() public
__get(mixed $name)
Magic method for lazy loading $components.
Parameters
-
string
$name Name of component to get.
Returns
\Cake\Controller\Component|null
A Component object or null.
_checkCipher() protected
_checkCipher(mixed $encrypt)
Helper method for validating encryption cipher names.
Parameters
-
string
$encrypt The cipher name.
Throws
RuntimeException
When an invalid cipher is provided.
_configDelete() protected
_configDelete(mixed $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(mixed $key)
Reads a config key.
Parameters
-
string|null
$key Key to read.
Returns
mixed
_configWrite() protected
_configWrite(mixed $key, mixed $value, mixed $merge)
Writes a config key.
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.
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config
_decode() protected
_decode(mixed $value, mixed $encrypt, mixed $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(mixed $values, mixed $mode, mixed $key)
Decrypts $value using public $type method in Security class
Parameters
-
string[]|string
$values Values to decrypt
-
string|false
$mode Encryption mode
-
string|null
$key optional Used as the security salt if specified.
Returns
string|array
Decrypted values
_delete() protected
_delete(mixed $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
_encrypt() protected
_encrypt(mixed $value, mixed $encrypt, mixed $key)
Encrypts $value using public $type method in Security class
Parameters
-
string|array
$value Value to encrypt
-
string|false
$encrypt Encryption mode to use. False disabled encryption.
-
string|null
$key optional Used as the security salt if specified.
Returns
string
Encoded values
_explode() protected
_explode(mixed $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
_getCookieEncryptionKey() protected
_getCookieEncryptionKey()
Returns the encryption key to be used.
Returns
string
_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.
_load() protected
_load(mixed $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(mixed $name, mixed $value)
Set cookie
Parameters
-
string
$name Name for cookie
-
string
$value Value for cookie
check() public
check(mixed $key)
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(mixed $key, mixed $value, mixed $merge)
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 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(mixed $keyname, mixed $option, mixed $value)
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.
-
array|string|null
$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(mixed $key, mixed $value)
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 The value to set.
Returns
$this
delete() public
delete(mixed $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
getConfig() public
getConfig(mixed $key, mixed $default)
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 The key to get or null for the whole config.
-
mixed|null
$default optional The return value when the key does not exist.
Returns
mixed|null
Configuration data at the named key or null if the key does not exist.
getConfigOrFail() public
getConfigOrFail(mixed $key)
Returns the config for this specific key.
The config value for this key must exist, it can never be null.
Parameters
-
string|null
$key The key to get.
Returns
mixed
Configuration data at the named key
Throws
InvalidArgumentException
getController() public
getController()
Get the controller this component is bound to.
Returns
\Cake\Controller\Controller
The bound controller.
implementedEvents() public
implementedEvents()
Events supported by this component.
Returns
array
initialize() public
initialize(array $config)
Initialize config data and properties.
Parameters
-
array
$config The config data.
log() public
log(mixed $message, mixed $level, mixed $context)
Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
Parameters
-
mixed
$message 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(mixed $key)
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
setConfig() public
setConfig(mixed $key, mixed $value, mixed $merge)
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 The value to set.
-
bool
$merge optional 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.
write() public
write(mixed $key, mixed $value)
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
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\Http\Response object.
Currently unused.
Type
\Cake\Http\Response|null
$_validCiphers protected
Valid cipher names for encrypted cookies.
Type
string[]
$_values protected
Values stored in the cookie.
Accessed in the controller using $this->Cookie->read('Name.key');
Type
array
$components public
Other Components this component uses.
Type
array
$request public
Request object
Type
\Cake\Http\ServerRequest
$response public
Response object
Type
\Cake\Http\Response
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.9/class-Cake.Controller.Component.CookieComponent.html