harmonyio / validation
Asynchronous validation library
Requires
- php: ^7.3
- ext-ctype: *
- ext-dom: *
- ext-fileinfo: *
- ext-filter: *
- ext-gd: *
- ext-hash: *
- ext-json: *
- ext-libxml: *
- ext-mbstring: *
- amphp/amp: ^2.1.1
- amphp/artax: ^3.0.14
- amphp/dns: ^0.9.13
- amphp/file: ^0.3.3
- amphp/parallel-functions: ^0.1.3
- amphp/process: ^1.0.2
- amphp/uri: ^0.1.3
- egulias/email-validator: ^2.1.1
- harmonyio/cache: ^1.0.0-rc1
- harmonyio/http-client: ^1.0.0-rc1
- myclabs/php-enum: ^1.6.4
- react/promise: ^2.7.0
- wikimedia/ip-set: ^2.0.0
Requires (Dev)
- harmonyio/php-codesniffer-ruleset: 1.0.0-rc1
- harmonyio/phpunit-extension: ^1.0.0-rc1
- maglnet/composer-require-checker: ^1.1.0
- phpunit/phpunit: ^7.5.1
- slevomat/coding-standard: ^4.8.6
- squizlabs/php_codesniffer: ^3.4.0
This package is auto-updated.
Last update: 2024-10-29 06:46:52 UTC
README
Async validation library
Requirements
- PHP 7.3
- ext-ctype
- ext-dom
- ext-fileinfo
- ext-filter
- ext-gd
- ext-hash
- ext-json
- ext-libxml
- ext-mbstring
- Redis
In addition for non-blocking context one of the following event libraries should be installed:
Installation
composer require harmonyio/validation
Usage
This library is based on the amphp concurrency framework.
Basic usage
Validating a value against a single rule:
<?php declare(strict_types=1); namespace HarmonyIO\Validation\Examples; use Amp\Loop; use HarmonyIO\Validation\Result\Result; use HarmonyIO\Validation\Rule\Numeric\NumericType; require_once '/path/to/vendor/autoload.php'; Loop::run(static function () { /** @var Result $result */ $result = yield (new NumericType())->validate(true); var_dump($result); });
This will result in the following Result
object:
object(HarmonyIO\Validation\Result\Result)#11 (2) { ["valid":"HarmonyIO\Validation\Result\Result":private]=> bool(false) ["errors":"HarmonyIO\Validation\Result\Result":private]=> array(1) { [0]=> object(HarmonyIO\Validation\Result\Error)#10 (2) { ["message":"HarmonyIO\Validation\Result\Error":private]=> string(19) "Numeric.NumericType" ["parameters":"HarmonyIO\Validation\Result\Error":private]=> array(0) { } } } }
Stacking validation rules
Validation rules can be stacked on top of each other when you want to apply multiple rules to the same value:
<?php declare(strict_types=1); namespace HarmonyIO\Validation\Examples; use Amp\Loop; use HarmonyIO\Validation\Result\Result; use HarmonyIO\Validation\Rule\Combinator\All; use HarmonyIO\Validation\Rule\Numeric\Maximum; use HarmonyIO\Validation\Rule\Numeric\Minimum; use HarmonyIO\Validation\Rule\Numeric\NumericType; require_once '/path/to/vendor/autoload.php'; Loop::run(static function () { /** @var Result $result */ $result = yield (new All( new NumericType(), new Minimum(1), new Maximum(100) ))->validate(102); var_dump($result); });
This will result in the following Result
object:
object(HarmonyIO\Validation\Result\Result)#11 (2) { ["valid":"HarmonyIO\Validation\Result\Result":private]=> bool(false) ["errors":"HarmonyIO\Validation\Result\Result":private]=> array(1) { [0]=> object(HarmonyIO\Validation\Result\Error)#26 (2) { ["message":"HarmonyIO\Validation\Result\Error":private]=> string(15) "Numeric.Maximum" ["parameters":"HarmonyIO\Validation\Result\Error":private]=> array(1) { [0]=> object(HarmonyIO\Validation\Result\Parameter)#24 (2) { ["key":"HarmonyIO\Validation\Result\Parameter":private]=> string(7) "maximum" ["value":"HarmonyIO\Validation\Result\Parameter":private]=> float(100) } } } } }
Validation rules
There is already an elaborate list of validation rules implemented. For an overview of all supported rules please see the documentation in the wiki.
All validation rules adhere to the same interface:
<?php declare(strict_types=1); namespace HarmonyIO\Validation\Rule; use Amp\Promise; interface Rule { /** * @param mixed $value * @return Promise<HarmonyIO\Validation\Result\Result> */ public function validate($value): Promise; }
This will ensure any value can always be passed in to be validated and it will always result in a promise which resolved to a Result
object.
If you are missing a validation rule feel free to open an issue.
Combinators
Combinators are a way to combine multiple validation rules into a single result.
This can be used to build more complex validation rules based on existing rules.
Results and errors
All validation always result in a HarmonyIO\Validation\Result\Result
object.
To check whether a value is valid after validating we can simply call the HarmonyIO\Validation\Result\Result::isValid()
method which returns a simple boolean.
If the validation fails the validation errors can be accessed using one of two methods on the Result
object:
HarmonyIO\Validation\Result\Result::getFirstError()
- Returns eithernull
when there were no errors or aHarmonyIO\Validation\Result\Error
object otherwiseHarmonyIO\Validation\Result\Result::getErrors()
- Returns an array withHarmonyIO\Validation\Result\Error
objects
Errors
When validation results in an invalid result at least one Error
object will be added to the Result
object.
An error object always has an error message (which can be used for translation for rendering in your project) and zero or more parameters.
Parameters are used when failed validation rules are based on dynamic values. I.e. when the validation rule for minimum length of text fails it will result in the following Error
object:
object(HarmonyIO\Validation\Result\Error)#17 (2) { ["message":"HarmonyIO\Validation\Result\Error":private]=> string(18) "Text.MinimumLength" ["parameters":"HarmonyIO\Validation\Result\Error":private]=> array(1) { [0]=> object(HarmonyIO\Validation\Result\Parameter)#15 (2) { ["key":"HarmonyIO\Validation\Result\Parameter":private]=> string(6) "length" ["value":"HarmonyIO\Validation\Result\Parameter":private]=> int(4) } } }
Traditional / blocking usage
Although this project is based on async programming it is also possible to use it in a more traditional blocking way using the wait()
helper function:
<?php declare(strict_types=1); namespace HarmonyIO\Validation\Examples; use HarmonyIO\Validation\Result\Result; use HarmonyIO\Validation\Rule\Numeric\NumericType; use function Amp\Promise\wait; require_once '/path/to/vendor/autoload.php'; /** @var Result $result */ $result = wait((new NumericType())->validate(true)); var_dump($result);
Rules
An overview of all implemented rules (including usage and version information) is documented in the wiki.