Download the PHP package vincent4vx/form without Composer

Form Validation and Hydration System

A simple form system with fast validation and object hydration. This library provides a way to validate form input data and populate an object with the validated data in a simple and efficient way. It uses code generation to improve performance, and provides a runtime fallback for development.

The philosophy of the library is :

• Use PHP structures to define your forms, instead of building them using a DSL, like a builder or a YAML file.
• The declared structure is the only actually used structure for validation and hydration. No obscure internal structure will be used, nor duplication of the data.
• Components are mostly immutable, allowing caching form instances.
• Heavily use of code generation to improve performance.

Installation

You can install this library using Composer:

Usage

Bootstrap

To use the form validation library, you first need to initialize the registry. An adapter to PSR-11-compatible dependency injection container can be used, such as PHP-DI or Symfony DI. If you don't use a dependency injection container, you can use the DefaultRegistry class.

Once you've initialized your container, you can use it to instantiate the library's form factory. Here's an example that shows how to instantiate the factories using the ContainerRegistry class provided with the library:

Simple usage

Once you have instantiated the form factory, you can use it to create your forms. First, you need to declare your form by declaring the fields it contains as public properties with attributes for validation and transformation rules.

Here's an example of a declaration for a user registration form:

To use this form, you can create an instance of the form using the form factory, and then use it to validate and hydrate your data:

Embedded forms

You can embed forms into other forms, using the Embedded or ArrayOf components.

Custom validator

The library provides a set of built-in validators, as you can see here, but you in a real-world application, you will probably need to create your own validators.

There is multiple ways to create a custom validator, depending on your needs (and time constraints).

Note: don't forget to handle optional fields in your custom validators, as they may be null.

The quick and dirty way

The easiest way to create a custom validator is to create a validation method in your form class, and annotate the property with the ValidationMethod constraint:

But this method has some drawbacks:

• Polluting your form class with validation methods
• Type safety of parameters is not enforced, nor the method name is checked at compile time
• Reusability is possible, but need to declare a class with static methods for each validation method
• Dependency injection is not possible

So, only use this method for proof of concept or disposable code.

Dirty, but with dependency injection

If you need to inject dependencies in your validation method, you can use the ValidateBy constraint with the validator class name, and implements the ConstraintValidatorInterface:

This method fixes most of the drawbacks of the previous method, but it's still cannot enforce type safety of parameters. So, it's reasonable to use this method if the validation does not require any parameter.

The clean way

Depending on your needs, there is two ways to create a clean validator:

• When dependency injection is not required, you can create a class that extends the SelfValidatedConstraint class. It will implement both the ConstraintValidatorInterface. So all you have to do is to declare parameters, and implement the validate() method.
• When dependency injection is required, you need to create two classes :
  • One that implements the ConstraintInterface, which will be used to declare parameters
  • And another one the ConstraintValidatorInterface, which will be used to validate the data

SelfValidatedConstraint

ConstraintInterface and ConstraintValidatorInterface

Code generation

By default, code generation is also performed on custom constraints by inlining the instantiation of the constraint class. For example, the property:

Will be compiled in code like this:

Which provides decent performance, but it's not optimal. So, you may want to generate the validation code yourself on simple constraints heavily used in your forms.

To do so, you can implement the ConstraintValidatorGeneratorInterface on the validator class (or constraint class in case of a self validated constraint).

See library source code for examples.

Custom transformers

Unlike validators, no quick and dirty way is provided to create custom transformers. So, two ways are available to create a custom transformer:

• When dependency injection is not required, you can create a class that implements the FieldTransformerInterface interface.
• When dependency injection is required, you need to create two classes :
  • One that implements the DelegatedFieldTransformerInterface interface, providing transformer parameters
  • And another one the ConfigurableFieldTransformerInterface interface, providing the transformer logic

FieldTransformerInterface

This is the simplest way to create a custom transformer, but it doesn't allow dependency injection. You simply have to:

• Create a class that implements the FieldTransformerInterface interface,
• Implements the transformFromHttp() for HTTP to form object transformation
• Implements the transformToHttp() for form object to HTTP transformation (if needed)
• Declare it as an attribute on the form property.

DelegatedFieldTransformerInterface

When you need some dependencies on your transformation logic, you should use the DelegatedFieldTransformerInterface interface. The transformation logic (and dependencies) will be provided by a class implementing the ConfigurableFieldTransformerInterface interface.

Code generation

The code generation is mostly the same as for validators, so you can refer to the validators section for more information.

To do so, you can implement the FieldTransformerGeneratorInterface on the transformer implementation class (i.e. class which implements FieldTransformerInterface or ConfigurableFieldTransformerInterface, but not DelegatedFieldTransformerInterface).

See library source code for examples.

API

Validation

ArrayShape

Source: src/Validator/Constraint/ArrayShape.php

The ArrayShape class is a PHP attribute that can be used to validate if the current field is an array and if it has the expected keys and values types.

Example:

Constructor:

The ArrayShape class constructor takes the following parameters:

Choice

Source: src/Validator/Constraint/Choice.php

Check if the value is in the given choices.

The value is checked with strict comparison, so ensure that the value is correctly cast. This constraint supports multiple choices (i.e. input value is an array). You can define labels for the choices by using a string key in the choices array.

Example:

Constructor:

EqualsWith

Source: src/Validator/Constraint/EqualsWith.php

Check if the current field value is equals to other field value.

Example:

Constructor:

EqualTo

Source: src/Validator/Constraint/EqualTo.php

Check that the field value is equal to the given value. This comparison use the simple comparison operator (==) and not the strict one (===).

Numeric and string values are supported. To ensure that the comparison is done in the same type, add a typehint to the field and use the same type on the constraint's value.

Example:

Constructor:

See also:

• IdenticalTo for a strict comparison
• NotEqualTo for the opposite constraint

GreaterThan

Source: src/Validator/Constraint/GreaterThan.php

Check that the field value is greater than the given value.

Numeric and string values are supported. To ensure that the comparison is done in the same type, add a typehint to the field and use the same type on the constraint's value.

Example:

Constructor:

See also:

• GreaterThanOrEqual for a greater or equal comparison
• LessThanOrEqual for the opposite constraint

GreaterThanOrEqual

Source: src/Validator/Constraint/GreaterThanOrEqual.php

Check that the field value is greater than or equal to the given value. Numeric and string values are supported. To ensure that the comparison is done in the same type, add a typehint to the field and use the same type on the constraint's value.

Example:

Constructor:

See also:

• GreaterThan for a greater without equal comparison.
• LessThan for the opposite constraint.

IdenticalTo

Source: src/Validator/Constraint/IdenticalTo.php

Check that the field value is the same as the given value. This comparison uses the strict comparison operator (===).

Numeric and string values are supported. The value type must be the same as the field type, and the field value must be cast using type hint or Cast transformer.

Example:

Constructor:

See also:

• EqualTo for a simple comparison
• NotIdenticalTo for the opposite constraint

Length

Source: src/Validator/Constraint/Length.php

Validate the length of a string field. If the field is not a string, this validator will be ignored.

This constraint allows you to check the length of a string field. You can define the minimum and maximum length, and customize the error message.

Example:

Constructor:

LessThan

Source: src/Validator/Constraint/LessThan.php

The LessThan constraint checks if the field value is less than the given value. The comparison uses the strict comparison operator < to ensure that the comparison is done in the same type.

Example:

Constructor:

See also:

• LessThanOrEqual for a less than or equal comparison.
• GreaterThanOrEqual for the opposite constraint.

LessThanOrEqual

Source: src/Validator/Constraint/LessThanOrEqual.php

Check that the field value is less than or equal to the given value

Numeric and string values are supported. To ensure that the comparison is done in the same type, add a typehint to the field and use the same type on the constraint's value.

Example:

Constructor:

See also:

• LessThan for a less without equal comparison
• GreaterThan for the opposite constraint

NotEqualTo

Source: src/Validator/Constraint/NotEqualTo.php

Check that the field value is equal to the given value. This comparison uses the simple comparison operator != and not the strict one !==.

Numeric and string values are supported. To ensure that the comparison is done in the same type, add a typehint to the field and use the same type on the constraint's value.

Example:

Constructor:

See also:

• NotIdenticalTo for a strict comparison.
• EqualTo for the opposite constraint.

NotIdenticalTo

Source: src/Validator/Constraint/NotIdenticalTo.php

Check that the field value is equal to the given value. This comparison uses the strict comparison operator !==. Numeric and string values are supported. The value type must be the same as the field type, and the field value must be cast using typehint or Cast transformer.

Example:

Constructor:

See also:

• NotEqualTo for a simple comparison
• IdenticalTo for the opposite constraint

PasswordStrength

Source: src/Validator/Constraint/PasswordStrength.php

Check the strength of a password field. The strength is a logarithmic value representing an approximation of the number of possible combinations.

This algorithm takes into account:

• The presence of lowercase letters
• The presence of uppercase letters
• The presence of digits
• The presence of special characters
• The length of the password

This check does not force the user to use a specific set of characters while still providing a good level of security. The strength should be chosen according to the password hashing algorithm used: slower algorithms make brute force attacks slower so a lower strength is acceptable. The recommended strength is 51, which takes around one month to brute force at one billion attempts per second.

Example:

Constructor:

Regex

Source: src/Validator/Constraint/Regex.php

Check if the field value matches the given regular expression using PCRE syntax. Generates an HTML5 "pattern" attribute if possible.

Example:

Constructor:

Required

Source: src/Validator/Constraint/Required.php

This constraint marks a field as required. The field will be considered valid if it is not null and not an empty string or array. Any other value will be considered valid, like 0, false, etc.

Note: this constraint is not required if the field is typed as non-nullable.

Example:

Constructor:

UploadedFile

Source: src/Validator/Constraint/UploadedFile.php

Check if the uploaded file is valid. Use PSR-7 UploadedFileInterface, so psr/http-message package is required to use this constraint.

Example:

Constructor:

ValidateArray

Source: src/Validator/Constraint/ValidateArray.php

Constraint for array validation. Will apply validation to each element of the array.

Example:

Constructor:

ValidateBy

Source: src/Validator/Constraint/ValidateBy.php

This is a generic constraint used to validate a field value using a custom validator instance. This class allows you to specify the validator class to use and an array of options to pass to the validator. It is important to note that it is preferable to use a custom constraint class instead of using the options array.

Example:

Constructor:

See also:

• Custom validator describes how to create a custom validator Here's an example of how you could convert the docblock for the ValidateVar class to a readme section:

ValidateVar

Source: src/Validator/Constraint/ValidateVar.php

Validate field value using filter_var() with FILTER_VALIDATE_* constant.

Example:

Constructor:

ValidationMethod

Source: src/Validator/Constraint/ValidationMethod.php

Validate a field value using a method call.

This method can be a static method on a given class or an instance method declared on the data object. The method will be called with the following arguments:

• the field value
• the data object (on the instance method, this parameter is same as $this)
• extra parameters, as variadic arguments

The method can return one of the following:

• null: the field is valid
• true: the field is valid
• a string: the field is invalid, the string is the error message
• a FieldError instance: the field is invalid
• false: the field is invalid, the error message is the default one

Example:

Constructor:

See also:

• Custom validators describes how to create a custom validator

Transformation

ArrayCast

Source: src/Transformer/Field/ArrayCast.php

Cast values of an array

The performed cast is a fail-safe operation :

• if the value cannot be cast, null will be returned
• in case of numeric type, invalid string will return 0 (or 0.0 on float)

Transformation to HTTP value will simply cast non-null value to array.

Example:

Constructor:

Cast

Source: src/Transformer/Field/Cast.php

Cast HTTP value to target type

This transformer is automatically added on typed properties The performed cast is a fail-safe operation :

• if the value cannot be cast, null will be returned
• in case of numeric type, invalid string will return 0 (or 0.0 on float)

Transformation to HTTP value will simply assume the value is already a normalized value

Example:

Csv

Source: src/Transformer/Field/Csv.php

Transform a CSV string to an array. This transformer use an implementation of RFC 4180, so it supports quoted values.

Example:

Constructor:

DateTimeTransformer

Source: src/Transformer/Field/DateTimeTransformer.php

Transform a date from a string to a DateTimeInterface object.

Example:

Constructor:

DefaultValue

Source: src/Transformer/Field/DefaultValue.php

Defines a default value for a field.

The default value is used when the field is not submitted. This transformer will be automatically added to the field if the default value is not null. You can define this transformer explicitly to ignore the default behavior.

Note: Be careful of the transformer order. If this attribute is defined before other transformers, the value should be an HTTP (i.e. not transformed) value. If this attribute is defined after other transformers, the value should be a PHP (i.e. transformed) value.

Example:

Enum

Source: src/Transformer/Field/Enum.php

Transform a value to its corresponding enum instance. It supports both UnitEnum and BackedEnum, and resolve the enum instance using the value or the name.

To define labels for the choices, implements the interface LabelInterface on the enum class.

Note: This transformer is case-sensitive

Example:

Constructor:

Json

Source: src/Transformer/Field/Json.php

Parse JSON string to PHP value.

Note: Transformation will fail if the JSON is invalid. Use TransformationError to change this behavior.

Example:

Constructor:

See also:

• ArrayShape to validate the JSON structure.

TransformEach

Source: src/Transformer/Field/TransformEach.php

Apply transformers on each element of an array. If the input value is not and array, it will be transformed as an array before applying the transformers.

Example:

Constructor:

Trim

Source: src/Transformer/Field/Trim.php

Trim the input value.

This transformer will remove all spaces at the beginning and at the end of the value. The transformation is only applied when transforming from HTTP.

Example:

TransformationError

Source: src/Transformer/Field/TransformationError.php

Configure error handling of transformation error.

By default, when transformation fails, the field will be considered as invalid, and the error message will be set to the error message of the first transformer that failed.

Note: this is not a transformer, but a configuration class.

Example:

Constructor:

Components

Checkbox

Source: src/Component/Checkbox.php

Handle HTTP checkbox input.

The field value is true when a value is present in the HTTP request and is equal to the given httpValue (default to "1"). The field value is false when the value is not present in the HTTP request or is not equal to the given httpValue. So, the field value is always a non-nullable boolean.

Note: the http value will be cast to string before comparison.

Example:

Csrf

Source: src/Component/Csrf/Csrf.php

Add a token to the form to prevent CSRF attacks.

To use this constraint, you must have the Symfony Security component installed (i.e. symfony/security-csrf). and register the CsrfManager service in the form registry.

The CSRF token can be regenerated on each request by setting the "refresh" option to true.

Example:

Constructor:

Internal working

The process of validating and hydrating a form is divided into 3 steps, plus a fourth optional step:

• The transformation step, which transforms the raw data into a normalized format that can be handled by PHP
• The hydration step, which populates the form object with the normalized data
• The validation step, which validates the form object
• And optionally, generation of view objects, which can be used to generate HTML forms

Each step can be compiled into a PHP class using code generation, which improves performance. Steps will be executed in the reverse order when importing data from the form object.

Transformation

The transformation is the first step of the form process when calling the FormInterface::submit() method. It's also the last step of the process when calling the FormInterface::import() method.

The transformation step is responsible for transforming the raw data into an array of properties that can be used to populate the form object on the following step.

So it will perform :

• data normalization, such as converting a string to an integer, or converting a date string to a DateTime object
• filtering, such as removing non-declared fields
• aliasing, such as renaming a field to match the form object property name

For example, the following HTTP form data:

Can be transformed into the following array:

During the import() step, the transformation will perform the reverse operation, so the previous array will be transformed into the following array:

To summarize, the transformation step will transform an HTTP form data array into a normalized and safe array that can be used to populate the form object, and vice versa.

See:

• FormTransformerInterface - The interface which perform the transformation step
• FieldTransformerInterface - The interface which perform the data transformation for each field

Hydration

The hydration step is the second step of the form process when calling the FormInterface::submit() method, and the first step when calling the FormInterface::import() method.

On the submit process, the hydration step is responsible for instantiate and populate the form object with the array from the transformation step. On the import process, the hydration step is responsible for extracting properties array from the form object.

See:

• DataMapperInterface - The interface which perform the hydration step
• PublicPropertyDataMapper - The default implementation

Validation

The validation step is the last step of the submit process. The validation is not performed when importing data from the form object.

This step will simply validate each property of the form object using the constraints declared on the form fields. It will return an array of FieldError objects, indexed by the property name.

Note: some errors can be raised by the transformation step. In this case, the validation of the field will be skipped, and the error of the transformation step will be returned instead.

See:

• ValidatorInterface - The interface which perform the validation of the whole form object
• ConstraintInterface - The interface for a field constraint
• ConstraintValidatorInterface - The interface for validate a single constraint

View generation

The view generation is an optional step that can be used to generate view objects from the form object. This step is triggered by calling the FormInterface::view() method.

If the form is a submitted or an imported one, the view will be generated from FilledFormInterface::httpValue().

See:

• FormViewInstantiatorInterface - The interface which perform the view generation
• FormView - The view object for a form
• FieldView - The view object for a field

Immutability

Most of the form components are immutable, which means that they will return a new instance when you call a method that modify the object.

So, each form process will return a new instance:

• The default form factory will return a new FormInterface instance
• FormInterface::submit() will return a new SubmittedFormInterface instance
• FormInterface::import() will return a new ImportedFormInterface instance

Each types only provide the methods that are actually available for this type, so you can't call FormInterface::value() for example.

The immutability allows to reuse or cache form instances (the default factory will always cache instances). But it came with a drawback: a new variable is required to store results of each form process.

Performance

See GitHub actions for the latest benchmark results.

A benchmark comparison has been made, using phpbench, between this library and Symfony forms, and vanilla PHP.

License

This library is licensed under the MIT license.