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:
  • Logical And
  • Logical Or
  • Logical Not

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.