Docs4dev
Docs
cakephp / 4.4 / class-cake.form.formprotector.html

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

Property Summary

  • $debugMessage protected
    string|null

    Error message providing detail for failed validation.

  • $fields protected
    array

    Fields list.

  • $unlockedFields protected
    array<string>

    Unlocked fields.

Method Summary

Method Detail

__construct() public

__construct(array<string, mixed> $data = [])

Construct.

Parameters

array<string, mixed> $data optional

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

__debugInfo() public

__debugInfo(): array<string, mixed>

Return debug info

Returns

array<string, mixed>

addField() public

addField(array<string>|string $field, bool $lock = true, mixed $value = null): $this

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

Parameters

array<string>|string $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 = ''): array<string, string>

Generate the token data.

Parameters

string $url optional

Form URL.

string $sessionId optional

Session Id.

Returns

array<string, string>

debugCheckFields() protected

debugCheckFields(array $dataFields, array $expectedFields = [], string $intKeyMessage = '', string $stringKeyMessage = '', string $missingMessage = ''): array<string>

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

array<string>

debugExpectedFields() protected

debugExpectedFields(array $expectedFields = [], string $missingMessage = ''): string|null

Generate debug message for the expected fields

Parameters

array $expectedFields optional

Expected fields

string $missingMessage optional

Message template

Returns

string|null

debugTokenNotMatching() protected

debugTokenNotMatching(array $formData, array $hashParts): string

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

extractFields() protected

extractFields(array $formData): array

Return the fields list for the hash calculation

Parameters

array $formData

Data array

Returns

array

extractHashParts() protected

extractHashParts(array<string, array> $formData): array<string, array>

Return hash parts for the token generation

Parameters

array<string, array> $formData

Form data.

Returns

array<string, array>

extractToken() protected

extractToken(mixed $formData): string|null

Extract token from data.

Parameters

mixed $formData

Data to validate.

Returns

string|null

generateHash() protected

generateHash(array $fields, array<string> $unlockedFields, string $url, string $sessionId): string

Generate validation hash.

Parameters

array $fields

Fields list.

array<string> $unlockedFields

Unlocked fields.

string $url

Form URL.

string $sessionId

Session Id.

Returns

string

getError() public

getError(): string|null

Get validation error message.

Returns

string|null

getFieldNameArray() protected

getFieldNameArray(string $name): array<string>

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

array<string>

matchExistingFields() protected

matchExistingFields(array $dataFields, array $expectedFields, string $intKeyMessage, string $stringKeyMessage): array<string>

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

array<string>

sortedUnlockedFields() protected

sortedUnlockedFields(array $formData): array<string>

Get the sorted unlocked string

Parameters

array $formData

Data array

Returns

array<string>

unlockField() public

unlockField(string $name): $this

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): bool

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<string>

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