Class
CsrfComponent
Provides CSRF protection & validation.
This component adds a CSRF token to a cookie. The cookie value is compared to request data, or the X-CSRF-Token header on each PATCH, POST, PUT, or DELETE request.
If the request data is missing or does not match the cookie data, an InvalidCsrfTokenException will be raised.
This component integrates with the FormHelper automatically and when
used together your forms will have CSRF tokens automatically added
when $this->Form->create(...) is used in a view.
Deprecated: 3.5.0 Use Cake\Http\Middleware\CsrfProtectionMiddleware instead.
Property Summary
-
$_componentMap protected
arrayA component lookup table used to lazy load component objects.
-
$_config protected
arrayRuntime config
-
$_configInitialized protected
boolWhether the config property has already been configured with defaults
-
$_defaultConfig protected
arrayDefault config for the CSRF handling.
-
$_registry protected
Cake\Controller\ComponentRegistryComponent registry class used to lazy load components.
-
$components public
arrayOther Components this component uses.
-
$request public deprecated
Cake\Http\ServerRequestRequest object
-
$response public deprecated
Cake\Http\ResponseResponse 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.
-
_configDelete() protected
Deletes a single config key.
-
_configRead() protected
Reads a config key.
-
_configWrite() protected
Writes a config key.
-
_setCookie() protected
Set the cookie in the response.
-
_validateToken() protected
Validate the request data against the cookie token.
-
config() public deprecated
Gets/Sets the config.
-
configShallow() public
Merge provided config with existing config. Unlike
config()which does a recursive merge for nested keys, this method does a simple merge. -
getConfig() public
Returns the config.
-
getConfigOrFail() public
Returns the config for this specific key.
-
getController() public
Get the controller this component is bound to.
-
implementedEvents() public
Events supported by this component.
-
initialize() public
Warn if CsrfComponent is used together with CsrfProtectionMiddleware
-
log() public
Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
-
setConfig() public
Sets the config.
-
startup() public
Startup callback.
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(): arrayReturns an array that can be used to describe the internal state of this object.
Returns
array__get() ¶ public
__get(string $name): Cake\Controller\Component|nullMagic method for lazy loading $components.
Parameters
-
string$name Name of component to get.
Returns
Cake\Controller\Component|null_configDelete() ¶ protected
_configDelete(string $key): voidDeletes a single config key.
Parameters
-
string$key Key to delete.
Returns
voidThrows
Cake\Core\Exception\Exceptionif attempting to clobber existing config
_configRead() ¶ protected
_configRead(string|null $key): mixedReads a config key.
Parameters
-
string|null$key Key to read.
Returns
mixed_configWrite() ¶ protected
_configWrite(string|array $key, mixed $value, bool|string $merge = false): voidWrites 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.
Returns
voidThrows
Cake\Core\Exception\Exceptionif attempting to clobber existing config
_setCookie() ¶ protected
_setCookie(Cake\Http\ServerRequest $request, Cake\Http\Response $response): arraySet the cookie in the response.
Also sets the request->params['_csrfToken'] so the newly minted token is available in the request data.
Parameters
-
Cake\Http\ServerRequest$request The request object.
-
Cake\Http\Response$response The response object.
Returns
array_validateToken() ¶ protected
_validateToken(Cake\Http\ServerRequest $request): voidValidate the request data against the cookie token.
Parameters
-
Cake\Http\ServerRequest$request The request to validate against.
Returns
voidThrows
Cake\Http\Exception\InvalidCsrfTokenExceptionwhen the CSRF token is invalid or missing.
config() ¶ public
config(string|array|null $key = null, mixed|null $value = null, bool $merge = true): mixedGets/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
mixedThrows
Cake\Core\Exception\ExceptionWhen trying to set a key that is invalid.
configShallow() ¶ public
configShallow(string|array $key, mixed|null $value = null): $thisMerge 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
$thisgetConfig() ¶ public
getConfig(string|null $key = null, mixed|null $default = null): mixed|nullReturns 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|nullgetConfigOrFail() ¶ public
getConfigOrFail(string|null $key): mixedReturns 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
mixedThrows
InvalidArgumentExceptiongetController() ¶ public
getController(): Cake\Controller\ControllerGet the controller this component is bound to.
Returns
Cake\Controller\ControllerimplementedEvents() ¶ public
implementedEvents(): arrayEvents 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
arrayinitialize() ¶ public
initialize(array $config): voidWarn if CsrfComponent is used together with CsrfProtectionMiddleware
Implement this method to avoid having to overwrite the constructor and call parent.
Parameters
-
array$config The config data.
Returns
voidlog() ¶ public
log(mixed $message, int|string $level = LogLevel::ERROR, string|array $context = []): boolConvenience 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
boolsetConfig() ¶ public
setConfig(string|array $key, mixed|null $value = null, bool $merge = true): $thisSets 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
$thisThrows
Cake\Core\Exception\ExceptionWhen trying to set a key that is invalid.
startup() ¶ public
startup(Cake\Event\Event $event): voidStartup callback.
Validates the CSRF token for POST data. If the request is a GET request, and the cookie value is absent a cookie will be set.
Once a cookie is set it will be copied into request->getParam('_csrfToken') so that application and framework code can easily access the csrf token.
RequestAction requests do not get checked, nor will they set a cookie should it be missing.
Parameters
-
Cake\Event\Event$event Event instance.
Returns
voidProperty Detail
$_configInitialized ¶ protected
Whether the config property has already been configured with defaults
Type
bool$_defaultConfig ¶ protected
Default config for the CSRF handling.
- cookieName = The name of the cookie to send.
- expiry = How long the CSRF token should last. Defaults to browser session.
- secure = Whether or not the cookie will be set with the Secure flag. Defaults to false.
- httpOnly = Whether or not the cookie will be set with the HttpOnly flag. Defaults to false.
- field = The form field to check. Changing this will also require configuring FormHelper.
Type
array$_registry ¶ protected
Component registry class used to lazy load components.
Type
Cake\Controller\ComponentRegistry