stellarwp / validation
An end-to-end ready PHP validation library
Installs: 291 057
Dependents: 0
Suggesters: 0
Security: 0
Stars: 13
Watchers: 8
Forks: 2
Open Issues: 7
Requires
- ext-json: *
- stellarwp/container-contract: 1.0.4
- stellarwp/field-conditions: ^1.0
Requires (Dev)
- codeception/module-asserts: ^1.0.0
- codeception/module-phpbrowser: ^1.0.0
- lucatume/di52: ^3.0
- lucatume/wp-browser: ^3.0.14
- phpunit/phpunit: ~6.0
README
This is a PHP validation library that is end-to-end ready. It is useful in any scenario wherein you have a set of values that you would like validated (and potentially even sanitized). It comes with an extendable list of rules that can be easily used to make using rules easy and declarative.
How to use
Installation
It is recommended to install this library using Composer. To do so, run the following command:
composer require stellarwp/validation
If using this in WordPress, it is strongly recommended that you use Strauss to avoid conflicts with other plugins.
Configuration and initialization
The library comes with a Config
class which is used to set up and initialize the library. Here's an example of how to
use it:
use StellarWP\Validation\Config; Config::setServiceContainer(MyContainer::class); // required Config::setHookPrefix('my_plugin_'); // recommended Config::setInvalidArgumentExceptionClass(MyInvalidArgumentException::class); // optional Config::setValidationExceptionClass(MyValidationException::class); // optional Config::initialize(); // mounts rules registrar to service container
The Service Container is used for dependency injection. The library uses this to store the ValidationRulesRegistrar
,
which keeps track of all the available rules. It is required to be set, and must implement
the Container Interface.
If you don't have a container, you can use the StellarWP Container or the
di52 container.
Validating data
The two main classes in the library are Validator
and ValidationRuleSet
. The Validator
class is used to validate
data, while the ValidationRuleSet
is used to define the rules for validation. The Validator
class is used as
follows:
use StellarWP\Validation\Validator; $values = [ 'name' => 'Bill Murray', 'age' => 76 ]; $labels = [ 'name' => 'Name', 'age' => 'Age' ]; $validator = new Validator([ 'name' => ['required'], 'age' => ['required', 'integer', 'min:18', 'max:150'] ], $values, $labels); if ($validator->passes()) { $safeData = $validator->validated(); } else { $errors = $validator->errors(); }
The Validator
class takes three arguments:
$values
- the values to be validated$rules
- the rules to be used for validation$labels
- the labels to be used for error messages
Validator::passes()
returns true if all rules pass
Validator::fails()
returns true if any rule fails
Validator::validated()
returns the validated data — any values without a rule will be removed, ensuring only trusted
data is returned.
Validator::errors()
returns an array of errors. The keys match the keys of the $values
array, and the values are
the error messages. If there are no errors an empty array is returned.
Rule arguments
The $rules
parameter passed to the Validator
can either be an array or rules, or a ValidationRuleSet
instance.
When passing an array, the rules can be defined in three ways:
$rules = [ 'name' => [ // As a string 'required', // As a Rule instance new \StellarWP\Validation\Rules\Min(1), // As a closure function ($value, Closure $fail, string $key, array $values) { if ($value === 'foo') { $fail('{field} cannot be foo'); } } ] ];
Adding rules to existing classes
Sometimes you have a class which represents an individual value, like a Value Object. In this case, you can use the HasValidationRules trait to add validation rules to the class. This trait adds various methods to the class for managing rules.
Adding new rules
The library comes with a number of rules out of the box, but you can easily add your own.
How rules are resolved
When adding rules to a rule set, you can either pass a string, a Rule
instance, or a closure. When a string is passed,
the library will attempt to resolve it using the ValidationRulesRegistrar. The
static Rule::id()
method is used to register the rule. So Min
, for example, has an id of min
. So when a string
rule is min:18
, the Min
rule will be resolved. Additional options can be passed to the rule after the colon.
This may seem like a bit of work, but it allows for easily readable, declarative rules when being used.
Basic rules
For a class to be a rule, it must implement the ValidationRule interface. See the interface for documentation on its methods.
Front-end compatible rules
If a class implements the ValidatesOnFrontEnd interface.
All rules live in the ValidationRuleSet
. The class supports being used in json_encode
function, wherein it will
generate a list of all rules which can be validated on the front-end. The age validation rules, for example, would
generate the following JSON:
{ "required": true, "integer": null, "min": 18, "max": 150 }
This JSON can be sent to the front-end and adapted to a library like Joi for front-end validation. This makes the following flow possible:
- Define your input rules on the server
- Pass the rules as JSON to the browser
- Convert the rules to your own system and validate in the browser
- Pass the resulting input data to the server
- Safely re-validate the inputs on the server
Front-end data is not secure, but it makes for a good user-experience. As such, defining it on one place and having it work the same on both the browser and server is excellent.
Sanitizing Rules
Rules can also provide sanitization — that is, they can modify the value before it is returned. To do this, implement the Sanitizer interface. Note that sanitization occurs after validation, so a value will only be sanitized if it first passes validation.
Finally, keep in mind that sanitization affects the value before it is sent to the following rule. This is useful in cases where you want to validate a value based on its type. Take age for example:
$rules = [ 'age' => ['required', 'integer', 'min:18', 'max:150'] ];
The integer
rule converts the value into an integer. So min:18
will check that the age numerically greater than or
equal to 18. Without the integer
rule, if age
was a string, then min:18
would count the number of characters, not
the numerical value.