Class FormProtector

Protects against form tampering. It ensures that:

  • Form's action (URL) is not modified.
  • Unknown / extra fields are not added to the form.
  • Existing fields have not been removed from the form.
  • Values of hidden inputs have not been changed.
Namespace: Cake\Form

Properties summary

  • $debugMessage protected
    string|null

    Error message providing detail for failed validation.

  • $fields protected
    array

    Fields list.

  • $unlockedFields protected
    array

    Unlocked fields.

Method Summary

Method Detail

__construct() public 

__construct(array $data)

Construct.

Parameters

array $data optional

Data array, can contain key unlockedFields with list of unlocked fields.

__debugInfo() public 

__debugInfo()

Return debug info

Returns

array

addField() public 

addField(mixed $field, bool $lock, mixed $value)

Determine which fields of a form should be used for hash.

Parameters

string|array $field

Reference to field to be secured. Can be dot separated string to indicate nesting or array of fieldname parts.

bool $lock optional

Whether this field should be part of the validation or excluded as part of the unlockedFields. Default true.

mixed $value optional

Field value, if value should not be tampered with.

Returns

$this

buildTokenData() public 

buildTokenData(string $url, string $sessionId)

Generate the token data.

Parameters

string $url optional

Form URL.

string $sessionId optional

Session Id.

Returns

array

The token data.

debugCheckFields() protected 

debugCheckFields(array $dataFields, array $expectedFields, string $intKeyMessage, string $stringKeyMessage, string $missingMessage)

Iterates data array to check against expected

Parameters

array $dataFields

Fields array, containing the POST data fields

array $expectedFields optional

Fields array, containing the expected fields we should have in POST

string $intKeyMessage optional

Message string if unexpected found in data fields indexed by int (not protected)

string $stringKeyMessage optional

Message string if tampered found in data fields indexed by string (protected).

string $missingMessage optional

Message string if missing field

Returns

string[]

Messages

debugExpectedFields() protected 

debugExpectedFields(array $expectedFields, string $missingMessage)

Generate debug message for the expected fields

Parameters

array $expectedFields optional

Expected fields

string $missingMessage optional

Message template

Returns

string|null

Error message about expected fields

debugTokenNotMatching() protected 

debugTokenNotMatching(array $formData, array $hashParts)

Create a message for humans to understand why Security token is not matching

Parameters

array $formData

Data.

array $hashParts

Elements used to generate the Token hash

Returns

string

Message explaining why the tokens are not matching

extractFields() protected 

extractFields(array $formData)

Return the fields list for the hash calculation

Parameters

array $formData

Data array

Returns

array

extractHashParts() protected 

extractHashParts(array $formData)

Return hash parts for the token generation

Parameters

array $formData

Form data.

Returns

array

extractToken() protected 

extractToken(mixed $formData)

Extract token from data.

Parameters

mixed $formData

Data to validate.

Returns

string|null

Fields token on success, null on failure.

generateHash() protected 

generateHash(array $fields, array $unlockedFields, string $url, string $sessionId)

Generate validation hash.

Parameters

array $fields

Fields list.

array $unlockedFields

Unlocked fields.

string $url

Form URL.

string $sessionId

Session Id.

Returns

string

getError() public 

getError()

Get validation error message.

Returns

string|null

getFieldNameArray() protected 

getFieldNameArray(string $name)

Parses the field name to create a dot separated name value for use in field hash. If fieldname is of form Model[field] or Model.field an array of fieldname parts like ['Model', 'field'] is returned.

Parameters

string $name

The form inputs name attribute.

Returns

string[]

Array of field name params like ['Model.field'] or ['Model', 'field'] for array fields or empty array if $name is empty.

matchExistingFields() protected 

matchExistingFields(array $dataFields, array $expectedFields, string $intKeyMessage, string $stringKeyMessage)

Generate array of messages for the existing fields in POST data, matching dataFields in $expectedFields will be unset

Parameters

array $dataFields

Fields array, containing the POST data fields

array $expectedFields

Fields array, containing the expected fields we should have in POST

string $intKeyMessage

Message string if unexpected found in data fields indexed by int (not protected)

string $stringKeyMessage

Message string if tampered found in data fields indexed by string (protected)

Returns

string[]

Error messages

sortedUnlockedFields() protected 

sortedUnlockedFields(array $formData)

Get the sorted unlocked string

Parameters

array $formData

Data array

Returns

string[]

unlockField() public 

unlockField(mixed $name)

Add to the list of fields that are currently unlocked.

Unlocked fields are not included in the field hash.

Parameters

string $name

The dot separated name for the field.

Returns

$this

validate() public 

validate(mixed $formData, string $url, string $sessionId)

Validate submitted form data.

Parameters

mixed $formData

Form data.

string $url

URL form was POSTed to.

string $sessionId

Session id for hash generation.

Returns

bool

Property Detail

$debugMessage protected

Error message providing detail for failed validation.

Type

string|null

$fields protected

Fields list.

Type

array

$unlockedFields protected

Unlocked fields.

Type

array

© 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/4.1/class-Cake.Form.FormProtector.html