softonic / jaxer
PHP Engine Rule to rule them all
Installs: 2 302
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 7
Forks: 0
Open Issues: 0
Requires
- php: >=8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.6
- mockery/mockery: ^1.0
- phpunit/phpunit: ^9.0
- rector/rector: ^0.11.20
- squizlabs/php_codesniffer: ^3
This package is auto-updated.
Last update: 2024-10-29 06:19:43 UTC
README
One rule engine to rule them all
Jaxer allows you to evaluate complex rules in an easy way and know the reason behind the validation result.
Main features
- Evaluate rules.
- Rules evaluation tracing.
- Provide generic rules:
Installation
You can require the last version of the package using composer
composer require softonic/jaxer
Usage
The rules are classes that needs to implement \Softonic\Jaxer\Rules\Rule
interface. They usually get their input
parameters through constructor like for example:
<?php use \Softonic\Jaxer\Rules\Rule; class IsNumberHigherThanFive implements Rule { /** * We receive the parameters from constructor. * You could also use specific setters or direct access to attribute. */ public function __construct(private int $number) { } /** * Business logic to be evaluated. */ public function isValid(): bool { return $this->number > 5; } /** * [Tracing] Context information to provide in case to know what happened in the evaluation. */ public function getContext(): array { return [ 'number' => $this->number, ]; } }
As you can see there is a part dedicated to the business logic in the isValid
method and a getContext
method that
allows you to track the rule information.
On the other hand, this library provide generic rules, which help to evaluate complex rules. These logical operation are: AND, OR and NOT.
Example using AndRule, OrRule and NotRule
<?php use Softonic\Jaxer\Rules\AndRule; use Softonic\Jaxer\Rules\NotRule; use Softonic\Jaxer\Rules\OrRule; use Softonic\Jaxer\Rules\Rule; use Softonic\Jaxer\Validation; class FalseRule implements Rule { public function isValid(): bool { return false; } public function getContext(): array { return []; } } class TrueRule implements Rule { public function isValid(): bool { return true; } public function getContext(): array { return []; } } $logicalRule = new OrRule( //true new AndRule( //false new TrueRule(), new FalseRule(), new TrueRule(), ), new AndRule( //true new NotRule( // true new FalseRule() ), new TrueRule() ) ); $validation = new Validation($logicalRule); $validation->isValid(); // true $validation->getContext(); // ['rule' => \Softonic\Jaxer\Rules\OrRule, 'context' => [...], 'evaluated' => true, 'isValid' => true]
After a validation is evaluated, you can execute isValid
as many times you want without performance impact because it
is evaluated only the first time it is called.
Advanced Usage
Rules with inner rules
Sometimes you need to create a rule that contain other rules, like for example AND, OR and NOT. Those rules contain other rules that need to be evaluated in validation time.
To evaluate a rule you need to encapsulate it in a Validation
object. It will decorate the rule adding state and a common context format.
Logical Not Example:
<?php namespace Softonic\Jaxer\Rules; use Softonic\Jaxer\Validation; class NotRule implements Rule { // Validation decorator private Validation $validation; public function __construct(private Rule $rule) { // Encapsulate rule inside a validation $this->validation = new Validation($rule); } public function isValid(): bool { // Validate the rule return !$this->validation->isValid(); } public function getContext(): array { // Get the validation context return $this->validation->getContext(); } }
Testing
softonic/jaxer
has a PHPUnit test suite, and a coding style compliance test suite using PHP CS Fixer.
To run the tests, run the following command from the project folder.
$ make tests
To open a terminal in the dev environment:
$ make debug
License
The Apache 2.0 license. Please see LICENSE for more information.