PHPackages                             hejunjie/simple-rule-engine - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. hejunjie/simple-rule-engine

ActiveLibrary[Validation & Sanitization](/categories/validation)

hejunjie/simple-rule-engine
===========================

一个轻量、易用的 PHP 规则引擎，支持多条件组合与动态规则执行，适用于业务规则判断、数据校验等场景 | A lightweight and flexible PHP rule engine supporting complex conditions and dynamic rule execution—ideal for business logic evaluation and data validation.

v1.0.3(1mo ago)7644↓90.8%11MITPHPPHP ^8.1

Since Apr 29Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/zxc7563598/php-simple-rule-engine)[ Packagist](https://packagist.org/packages/hejunjie/simple-rule-engine)[ RSS](/packages/hejunjie-simple-rule-engine/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (4)Dependencies (3)Versions (5)Used By (1)

hejunjie/simple-rule-engine
===========================

[](#hejunjiesimple-rule-engine)

[简体中文](./README.zh-CN.md) | English

A lightweight, easy-to-use PHP rule engine supporting multi-condition combinations and dynamic rule execution — ideal for business logic evaluation and data validation.

> This project has been parsed by [Zread](https://zread.ai/zxc7563598/php-simple-rule-engine). Click to explore the project structure and code navigation.

---

✨ Features
----------

[](#-features)

- **Clean API**: Build and execute rules in just a few lines with `Rule` + `Engine`, supporting AND / OR combination logic.
- **Rich Built-in Operators**: 17 operators out of the box covering comparison, string, array, and date scenarios.
- **Highly Extensible**: Register custom operators by implementing the `OperatorInterface` to handle specialized business needs.
- **Decoupled Rules and Data**: Rule definitions are fully separated from data evaluation, supporting arrays, objects, and more.
- **Detailed Evaluation Feedback**: `evaluateWithDetails` returns the pass/fail status of each rule, making debugging and logging straightforward.

---

📋 Requirements
--------------

[](#-requirements)

- PHP >= 8.1
- [nesbot/carbon](https://github.com/briannesbitt/Carbon) ^3.9 (required by date operators)

---

📦 Installation
--------------

[](#-installation)

```
composer require hejunjie/simple-rule-engine
```

---

🚀 Quick Start
-------------

[](#-quick-start)

```
use Hejunjie\SimpleRuleEngine\Rule;
use Hejunjie\SimpleRuleEngine\Engine;

// 1. Define rules
$rules = [
    new Rule('age', '>=', 18, 'Age must be 18 or older'),
    new Rule('country', '==', 'SG', 'Country must be Singapore'),
];

// 2. Prepare data
$data = [
    'age' => 20,
    'country' => 'SG',
];

// 3. Evaluate
$result = Engine::evaluate($rules, $data, 'AND'); // true
```

---

📖 Usage
-------

[](#-usage)

### Basic Evaluation

[](#basic-evaluation)

`Engine::evaluate()` accepts a list of rules, data, and a combination strategy, returning a boolean.

```
$rules = [
    new Rule('score', '>=', 60, 'Score is passing'),
    new Rule('score', '=', 18, 'Age must be 18 or older'),
    new Rule('vip', '==', true, 'Must be a VIP user'),
];

$data = ['age' => 20, 'vip' => false];

$details = Engine::evaluateWithDetails($rules, $data);
// [
//     ['description' => 'Age must be 18 or older', 'passed' => true],
//     ['description' => 'Must be a VIP user',      'passed' => false],
// ]
```

### Using RuleGroup

[](#using-rulegroup)

If you need more flexible composition (e.g., reusing the same group of rules across different scenarios), you can use `RuleGroup` directly:

```
use Hejunjie\SimpleRuleEngine\RuleGroup;

$group = new RuleGroup([
    new Rule('status', '==', 'active', 'Status is active'),
    new Rule('level', '>=', 3, 'Level is 3 or above'),
], 'AND');

$data = ['status' => 'active', 'level' => 5];

$group->evaluate($data);           // true
$group->evaluateWithDetails($data); // Returns detailed evaluation array
```

### Custom Operators

[](#custom-operators)

Implement the `OperatorInterface` and register through `OperatorFactory`:

```
use Hejunjie\SimpleRuleEngine\Interface\OperatorInterface;
use Hejunjie\SimpleRuleEngine\OperatorFactory;

class ModOperator implements OperatorInterface
{
    public function evaluate(mixed $fieldValue, mixed $ruleValue): bool
    {
        return $fieldValue % $ruleValue === 0;
    }

    public function name(): string
    {
        return 'mod';
    }
}

// Register
OperatorFactory::getInstance()->register(new ModOperator());

// Use
$rule = new Rule('number', 'mod', 3, 'Number is divisible by 3');
$rule->evaluate(['number' => 9]); // true
```

---

🧩 Built-in Operators
--------------------

[](#-built-in-operators)

### Comparison Operators

[](#comparison-operators)

OperatorDescriptionExample Value`==`Equal to`18``!=`Not equal to`18``>`Greater than`18``>=`Greater than or equal to`18``