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.
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
Cake\Network\RequestRequest object
-
$response public
Cake\Network\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
Delete a single config key
-
_configRead() protected
Read a config variable
-
_configWrite() protected
Write a config variable
-
_setCookie() protected
Set the cookie in the response.
-
_validateToken() protected
Validate the request data against the cookie token.
-
config() public
Usage
-
configShallow() public
Merge provided config with existing config. Unlike
config()which does a recursive merge for nested keys, this method does a simple merge. -
implementedEvents() public
Events supported by this component.
-
initialize() public
Constructor hook method.
-
log() public
Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
-
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): mixedMagic method for lazy loading $components.
Parameters
-
string$name Name of component to get.
Returns
mixedA Component object or null.
_configDelete() ¶ protected
_configDelete(string $key): voidDelete 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): mixedRead a config variable
Parameters
-
string|null$key Key to read.
Returns
mixed_configWrite() ¶ protected
_configWrite(string|array $key, mixed $value, bool|string $merge = false): voidWrite 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
voidThrows
Cake\Core\Exception\Exceptionif attempting to clobber existing config
_setCookie() ¶ protected
_setCookie(Cake\Network\Request $request, Cake\Network\Response $response): voidSet the cookie in the response.
Also sets the request->params['_csrfToken'] so the newly minted token is available in the request data.
Parameters
-
Cake\Network\Request$request The request object.
-
Cake\Network\Response$response The response object.
Returns
void_validateToken() ¶ protected
_validateToken(Cake\Network\Request $request): voidValidate the request data against the cookie token.
Parameters
-
Cake\Network\Request$request The request to validate against.
Returns
voidThrows
Cake\Network\Exception\InvalidCsrfTokenExceptionwhen the CSRF token is invalid or missing.
config() ¶ public
config(string|array|null $key = null, mixed|null $value = null, bool $merge = true): mixedUsage
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
mixedConfig value being read, or the object itself on write operations.
Throws
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->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
$thisThe object itself.
implementedEvents() ¶ 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): voidConstructor hook method.
Implement this method to avoid having to overwrite the constructor and call parent.
Parameters
-
array$config The configuration settings provided to this component.
Returns
voidlog() ¶ public
log(mixed $msg, 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$msg Log message.
-
int|string$level optional Error level.
-
string|array$context optional Additional log data relevant to this message.
Returns
boolSuccess of log write.
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->params['_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