Easy & Secure Whitelist Validation for PHP
, (*1)
This library provides whitelist validation ("accept known good") that is perfectly suited for building secure REST services. It uses programming language independent validation rules (plain array) that can be reused for additional client-side validation (JavaScript) or passed to template rendering engines such as Twig. By design, it is compatible with any framework and input source (HTML, REST, RPC, ...)., (*2)
A major advantage of this data source agnostic approach is that developers can do bottom-up development using unit tests to find bugs early and work on validation rules without an existing HTML frontend or storage backend. Use case specific input value validation is also more secure than general model validation, which often relies on a blacklist ("reject known bad")., (*3)
Besides basic validation rules such as type or length, more advanced features are supported as well - for example dependent fields, internationalization and multi-page forms. Validated values can be fetched individually, as flat array, by tag or by page., (*4)
The usage is simple: Form classes can inherit their definitions from each other. If needed, validation behavior can be changed using standard object-oriented methodologies. You don't need to hold a PhD in design patterns to understand how it works., (*5)
The following visualization highlights the differences between client-side, form (input value) and model validation. Model validation generally operates on trusted data (internal system state) and should be repeatable at any point in time while input validation explicitly operates once on data that comes from untrusted sources (depending on the use case and user privileges). This separation makes it possible to build reusable models, controllers and forms that can be coupled through dependency injection (see REST controller example)., (*6)
Think of form validation as whitelist validation ("accept known good") and model validation as blacklist validation ("reject known bad"). Whitelist validation is more secure while blacklist validation prevents your model layer from being overly constrained to very specific use cases., (*7)
Invalid model data should always cause an exception to be thrown (otherwise the application can continue running without noticing the mistake) while invalid input values coming from external sources are not unexpected, but rather common (unless you got users that never make mistakes). Validation within a specific model may not be possible at all, if a set of input values must be validated together (because they depend on each other) but individual values are then stored in different models - at least it can create additional dependencies between models that would not be there otherwise up to the point that all models depend on each other. In short: The application may still work as expected, but the code is a mess., (*8)
From a theoretical standpoint, any complex system has more internal state than it exposes to the outside, thus it is never sufficient to use model validation only - except the model provides two sets of methods: some that are used internally and some that can be exposed to arbitrary input data from any source. Aside from side-effects such as limited user feedback (exception messages) and bloated model code, this approach may easily lead to serious security flaws. Malicious input data is a much higher threat to multi-user Web applications than to classical single-user desktop applications. Simple blacklist model validation may be fully sufficient for desktop applications, which are in full control of the user interface (view layer)., (*9)
Client-side (JavaScript or HTML) form validation is always just a convenience feature and not reliable. However, with this library you can (at least partly) reuse existing server-side form validation rules to perform client-side validation, since they can be easily converted to JSON (for JavaScript) or be passed to template rendering engines such as Twig or Smarty (for HTML). Reusing model layer validation rules in a similar fashion is at least difficult, if not impossible., (*10)
See also Where to include business rule validation (OWASP)., (*11)
, (*12)
REST Request Validation Example
This example shows how to validate user input in a REST controller context. Note, how easy it is to avoid the deeply nested structures you often find in validation code. User model and form are injected as dependencies., (*13)
<?php
class UserController
{
protected $user;
protected $form;
public function __construct(UserModel $user, UserForm $form)
{
$this->user = $user;
$this->form = $form;
}
// Update User
public function putAction(int $id, Request $request): array
{
// Find entity (throws exception, if not found)
$this->user->find($id);
// Form initialization with current values
$this->form->setDefinedValues($this->user->getValues());
// Set input values
$this->form->setDefinedWritableValues($request->request->all());
// Validation
$this->form->validate();
if($this->form->hasErrors()) {
throw new FormInvalidException($this->form->getFirstError());
}
// Update values in database
$this->user->update($this->form->getValues());
// Return updated values
return $this->user->getValues();
}
// Return form fields incl current values for User
public function optionsAction(int $id): array
{
// Find entity (throws exception, if not found)
$this->user->find($id);
// Form initialization with current values
$this->form->setDefinedValues($this->user->getValues());
// Returns form as JSON compatible array incl all values
return $this->form->getAsArray();
}
}
See also Doctrine ActiveRecord - Object-oriented CRUD for Doctrine DBAL, (*14)
Configuration
A detailed overview of field properties can be found below. $_('label') is used for optional translation of field captions or other strings - a number of different translation file formats such as YAML are supported for that (see Symfony Components documentation), (*15)
use InputValidation\Form;
class UserForm extends Form
{
protected function init(array $params = array())
{
$definition = [
'username' => [
'type' => 'string',
'caption' => $this->_('username'),
'required' => true,
'min' => 3,
'max' => 15
],
'email' => [
'type' => 'email',
'caption' => $this->_('email_address'),
'required' => true
],
'gender' => [
'type' => 'string',
'caption' => $this->_('gender'),
'required' => false,
'options' => [
'm' => 'Male',
'f' => 'Female',
'o' => 'Other'
],
'optional' => true
],
'birthday' => [
'type' => 'date',
'caption' => $this->_('birthday'),
'required' => false
],
'password' => [
'type' => 'string',
'caption' => $this->_('password'),
'required' => true,
'min' => 5,
'max' => 30
],
'password_again' => [
'type' => 'string',
'caption' => $this->_('password_again'),
'required' => true,
'matches' => 'password'
],
'continent' => [
'type' => 'string',
'caption' => $this->_('region'),
'required' => true,
'options' => [
'north_america' => 'North America',
'south_america' => 'South Amertica',
'europe' => 'Europe,
'asia' => 'Asia',
'australia' => 'Australia'
]
]
];
$this->setDefinition($definition);
}
}
Properties
| Property |
Description |
| caption |
Field title (used for form rendering and in validation messages) |
| type |
Data type: int, numeric, scalar, list, bool, string, email, ip, url, date, datetime, time and switch |
| type_params |
Optional parameters for data type validation |
| options |
Array of possible values for the field (for select lists or radio button groups) |
| min |
Minimum value for numbers/dates, length for strings or number of elements for lists |
| max |
Maximum value for numbers/dates, length for strings or number of elements for lists |
| required |
Field cannot be empty (if false, setDefinedValues() and setDefinedWritableValues() still throw an exception, if it does not exist at all) |
| optional |
setDefinedValues() and setDefinedWritableValues() don't throw an exception, if the field is missing in the input values (usefull for checkboxes or certain JavaScript frameworks, that do not submit any data for empty form elements e.g. AngularJS) |
| readonly |
User is not allowed to change the field (not writable) |
| hidden |
User can not see the field (no impact on the validation) |
| default |
Default value |
| regex |
Regular expression to match against |
| matches |
Field value must match another form field (e.g. for password or email validation). Property can be prefixed with "!" to state that the fields must be different. |
| depends |
Field is required, if the given form field is not empty |
| depends_value |
Field is required, if the field defined in "depends" has this value |
| depends_value_empty |
Field is required, if the field defined in "depends" is empty |
| depends_first_option |
Field is required, if the field defined in "depends" has the first value (see "options") |
| depends_last_option |
Field is required, if the field defined in "depends" has the last value (see "options") |
| page |
Page number for multi-page forms |
| tags |
Optional list of tags (can be used to extract values by tag, see getValuesByTag()) |
You can create new form instances manually..., (*16)
use InputValidation\Form;
use InputValidation\Form\Validator;
use InputValidation\Form\Options\YamlOptions;
use Symfony\Component\Translation\Translator;
use Symfony\Component\Translation\MessageSelector;
use Symfony\Component\Translation\Loader\YamlFileLoader;
use Symfony\Component\Translation\Loader\ArrayLoader;
$translator = new Translator('en', new MessageSelector);
$translator->addLoader('yaml', new YamlFileLoader);
$translator->addLoader('array', new ArrayLoader);
$validator = new Validator();
$options = new YamlOptions($translator);
$form = new Form($translator, $validator, $options);
... or using the convenient InputValidation\Form\Factory:, (*17)
$formFactory = new InputValidation\Form\Factory($translator, $validator, $options);
$formFactory->setFactoryNamespace('App\Form');
$formFactory->setFactoryPostfix('Form');
$formFactory->create('User'); // Returns instance of App\Form\UserForm
API
__construct(Translator $translator, Form\Validator $validator, Form\OptionsInterface $options, array $params = array()), (*18)
The constructor requires instances of Symfony\Component\Translation\TranslatorInterface, InputValidation\Form\Validator, InputValidation\Form\OptionsInterface and an optional set of arbitrary parameters, which are passed to init(array $params = array()) (protected method for initializing the form)., (*19)
setOptions(Form\OptionsInterface $options), (*20)
Sets an optional class instance to automatically fill option lists (see "options" form field property). OptionsInterface only requires a method get($listName) that returns an array of options., (*21)
getOptions(): Form\OptionsInterface, (*22)
Returns the options instance, (*23)
options(string $listName): array, (*24)
Returns a list of options e.g. countries:, (*25)
'country' => array(
'type' => 'string',
'caption' => 'Country',
'default' => 'DE',
'options' => $this->form->options('countries')
)
optionsWithDefault(string $listName, string $defaultLabel = ''): array, (*26)
Returns a list of options with default label for no selection, (*27)
'country' => array(
'type' => 'string',
'caption' => 'Country',
'required' => true,
'options' => $this->form->optionsWithDefault('countries')
)
getTranslator(): Translator, (*28)
Returns the Translator instance (see __construct), (*29)
setTranslator(Translator $translator), (*30)
Sets the Translator instance (see __construct), (*31)
getValidator(): Validator, (*32)
Returns the Validator instance (see __construct), (*33)
setValidator(Validator $validator), (*34)
Sets the Validator instance (see __construct), (*35)
getLocale(), (*36)
Returns the current locale e.g. en, de or fr, (*37)
setLocale($locale), (*38)
Sets the current locale e.g. en, de or fr, (*39)
setDefinition(array $definition), (*40)
Sets the form field definition array (see example and form field properties), (*41)
getDefinition($key = null, $propertyName = null): mixed, (*42)
Returns the form field definition(s). If $key is null, definitions for all fields are returned. If $propertyName is null and $key is not null, only the definition of the given field key are returned. If both arguments are not null, only the definition of the given form field property is returned (for example, getDefinition('firstname', 'type') might return 'string'). A FormException is thrown otherwise., (*43)
getFieldDefinition(string $name): array, (*44)
Returns form field definition as array (wrapper for getDefinition), (*45)
getFieldProperty(string $name, string $property): mixed, (*46)
Returns a field property from the form definition (wrapper for getDefinition), (*47)
addDefinition($key, array $definition), (*48)
Adds a single form field definition (see form field properties), (*49)
changeDefinition($key, array $changes), (*50)
Changes a single form field definition (see form field properties), (*51)
setGroups(array $groups), (*52)
Sets form field groups (optional feature, if you want to reuse your form definition to reder the form as HTML)., (*53)
Example:, (*54)
$form->setGroups(
array(
'name' => array('firstname', 'lastname'),
'address' => array('street', 'housenr', 'zip', 'city')
)
);
getFieldAsArray(string $key): array, (*55)
Returns field definition and value as JSON compatible array:, (*56)
array (
'name' => 'country',
'caption' => 'Country',
'default' => 'DE',
'type' => 'string',
'options' => array (
array (
'option' => 'US',
'label' => 'United States',
),
array (
'option' => 'GB',
'label' => 'United Kingdom',
),
array (
'option' => 'DE',
'label' => 'Germany',
),
),
'value' => 'DE',
'uid' => 'id58a401f5a54e6',
),
getAsArray(): array, (*57)
Returns the complete form (definition and all values) as JSON compatible array, which can be used to render the form in templates:, (*58)
array (
'company' => array (
'name' => 'company',
'caption' => 'Company',
'type' => 'string',
'value' => 'IBM',
'uid' => 'id58a401f5a54d6',
),
'country' => array (
'name' => 'country',
'caption' => 'Country',
'default' => 'DE',
'type' => 'string',
'options' => array (
array (
'option' => 'US',
'label' => 'United States',
),
array (
'option' => 'GB',
'label' => 'United Kingdom',
),
array (
'option' => 'DE',
'label' => 'Germany',
),
),
'value' => 'DE',
'uid' => 'id58a401f5a54e6',
),
),
getAsGroupedArray(): array, (*59)
Returns grouped form field definitions and values (you must use setGroups() first):, (*60)
array(
'person' => array (
'group_name' => 'person',
'group_caption' => 'Person',
'fields' => array(
'person' => array (
'name' => 'firstname',
'caption' => 'First Name',
'type' => 'string',
'readonly' => true,
'value' => NULL,
'uid' => 'id58a401f5a5267',
),
'lastname' => array (
'name' => 'lastname',
'caption' => 'Last Name',
'type' => 'string',
'readonly' => false,
'value' => 'Mander',
'uid' => 'id58a401f5a5279',
),
),
),
'location' => array (
'group_name' => 'location',
'group_caption' => 'Location',
'fields' => array (
'company' => array (
'name' => 'company',
'caption' => 'Company',
'type' => 'string',
'value' => 'IBM',
'uid' => 'id58a401f5a54d6',
),
'country' => array (
'name' => 'country',
'caption' => 'Country',
'type' => 'string',
'default' => 'DE',
'options' => array (
array (
'option' => 'US',
'label' => 'United States',
),
array (
'option' => 'GB',
'label' => 'United Kingdom',
),
array (
'option' => 'DE',
'label' => 'Germany',
),
),
'value' => 'DE',
'uid' => 'id58a401f5a54e6',
),
),
),
),
setAllValues(array $values), (*61)
Sets all form values (does not check, if the fields exist or if the fields are writable by the user). Throws an exception, if you try to set values for undefined fields., (*62)
setDefinedValues(array $values), (*63)
Iterates through the form definition and sets the values for fields, that are present in the form definition., (*64)
setWritableValues(array $values), (*65)
Iterates through the passed value array and sets the values for fields, that are writable by the user., (*66)
setDefinedWritableValues(array $values), (*67)
Sets the values for fields, that are present in the form definition and that are writable by the user (recommended method for most use cases)., (*68)
setWritableValuesOnPage(array $values, $page), (*69)
Sets the values for fields on the given page, that are present in the form definition and that are writable by the user (recommended method for most use cases, if the form contains multiple pages)., (*70)
getValuesByPage(), (*71)
Returns the form values for all elements grouped by page., (*72)
getValuesByTag($tag), (*73)
Returns the form values for all elements by tag (see "tags" form field property), (*74)
getValues(), (*75)
Returns all form field values, (*76)
getWritableValues(), (*77)
Returns all user writable form field values, (*78)
translate($token, array $params = array()), (*79)
Uses the Translator adapter to translate the given string/token (accepts optional parameters for the translation string)., (*80)
_($token, array $params = array()), (*81)
Alias for translate(), (*82)
addError($key, $token, array $params = array()), (*83)
Adds a validation error (uses translate() for the error message internally), (*84)
validate(), (*85)
Validates all form field values. You can use getErrors(), getErrorsByPage(), isValid() and hasErrors() to get the validation results., (*86)
hasErrors(): bool, (*87)
Returns true, if the form has errors, (*88)
isValid(): bool, (*89)
eturns true, if the form is valid (has no errors), (*90)
getErrors(): array, (*91)
Returns all errors and throws an exception, if the validation was not performed yet (you must call validate() before calling getErrors())., (*92)
getFirstError(): string, (*93)
Returns the first error as string, (*94)
getErrorsAsText(): string, (*95)
Returns all errors as indented text (for command line applications), (*96)
getErrorsByPage(): array, (*97)
Returns all errors grouped by page and throws an exception, if the validation was not performed yet (you must call validate() before calling getErrorsByPage())., (*98)
clearErrors(), (*99)
Resets the validation and clears all errors, (*100)
getHash(): string, (*101)
Returns hash that uniquely identifies the form (for caching comprehensive forms), (*102)
Composer
To use this library in your project, simply run composer require symlex/input-validation or
add "symlex/input-validation" to your composer.json file and run composer update:, (*103)
{
"require": {
"php": ">=7.1",
"symlex/input-validation": "^4.0"
}
}
About
InputValidation is maintained by Michael Mayer.
Feel free to send an e-mail to hello@symlex.org if you have any questions,
need commercial support or just want to say hello.
We welcome contributions of any kind. If you have a bug or an idea, read our
guide before opening an issue., (*104)
Wallogit.com
