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.
Property Summary
-
$debugMessage protected
string|nullError message providing detail for failed validation.
-
$fields protected
arrayFields list.
-
$unlockedFields protected
list<string>Unlocked fields.
Method Summary
-
__construct() public
Construct.
-
__debugInfo() public
Return debug info
-
addField() public
Determine which fields of a form should be used for hash.
-
buildTokenData() public
Generate the token data.
-
debugCheckFields() protected
Iterates data array to check against expected
-
debugExpectedFields() protected
Generate debug message for the expected fields
-
debugTokenNotMatching() protected
Create a message for humans to understand why Security token is not matching
-
extractFields() protected
Return the fields list for the hash calculation
-
extractHashParts() protected
Return hash parts for the token generation
-
extractToken() protected
Extract token from data.
-
generateHash() protected
Generate validation hash.
-
getError() public
Get validation error message.
-
getFieldNameArray() protected
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.
-
matchExistingFields() protected
Generate array of messages for the existing fields in POST data, matching dataFields in $expectedFields will be unset
-
sortedUnlockedFields() protected
Get the sorted unlocked string
-
unlockField() public
Add to the list of fields that are currently unlocked.
-
validate() public
Validate submitted form data.
Method Detail
__construct() ¶ public
__construct(array<string, mixed> $data = [])Construct.
Parameters
-
array<string, mixed>$data optional Data array, can contain key
unlockedFieldswith list of unlocked fields.
__debugInfo() ¶ public
__debugInfo(): array<string, mixed>Return debug info
Returns
array<string, mixed>addField() ¶ public
addField(list<string>|string $field, bool $lock = true, mixed $value = null): $thisDetermine which fields of a form should be used for hash.
Parameters
-
list<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
$thisbuildTokenData() ¶ 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 = ''): list<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
list<string>debugExpectedFields() ¶ protected
debugExpectedFields(array $expectedFields = [], string $missingMessage = ''): string|nullGenerate debug message for the expected fields
Parameters
-
array$expectedFields optional Expected fields
-
string$missingMessage optional Message template
Returns
string|nulldebugTokenNotMatching() ¶ protected
debugTokenNotMatching(array $formData, array $hashParts): stringCreate 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
stringextractFields() ¶ protected
extractFields(array $formData): arrayReturn the fields list for the hash calculation
Parameters
-
array$formData Data array
Returns
arrayextractHashParts() ¶ 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|nullExtract token from data.
Parameters
-
mixed$formData Data to validate.
Returns
string|nullgenerateHash() ¶ protected
generateHash(array $fields, list<string> $unlockedFields, string $url, string $sessionId): stringGenerate validation hash.
Parameters
-
array$fields Fields list.
-
list<string>$unlockedFields Unlocked fields.
-
string$url Form URL.
-
string$sessionId Session Id.
Returns
stringgetFieldNameArray() ¶ protected
getFieldNameArray(string $name): list<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
list<string>matchExistingFields() ¶ protected
matchExistingFields(array $dataFields, array $expectedFields, string $intKeyMessage, string $stringKeyMessage): list<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
list<string>sortedUnlockedFields() ¶ protected
sortedUnlockedFields(array $formData): list<string>Get the sorted unlocked string
Parameters
-
array$formData Data array
Returns
list<string>unlockField() ¶ public
unlockField(string $name): $thisAdd 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
$thisvalidate() ¶ public
validate(mixed $formData, string $url, string $sessionId): boolValidate submitted form data.
Parameters
-
mixed$formData Form data.
-
string$url URL form was POSTed to.
-
string$sessionId Session id for hash generation.
Returns
bool