README

Lightweight business rule engine with declarative conditions and actions.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/php-rule-engine

Usage

Basic Rule

use PhilipRehberger\RuleEngine\RuleEngine;

$result = RuleEngine::create()
    ->rule('adult')
    ->when('age', '>=', 18)
    ->then(fn ($ctx) => "Welcome, {$ctx['name']}!")
    ->build()
    ->evaluate(['name' => 'Alice', 'age' => 25]);

$result->hasMatches(); // true
$result->first()->actionResult; // "Welcome, Alice!"

Multiple Conditions

$result = RuleEngine::create()
    ->rule('vip-discount')
    ->when('role', '=', 'vip')
    ->andWhen('total', '>=', 100)
    ->then(fn () => ['discount' => 0.2])
    ->build()
    ->rule('bulk-discount')
    ->when('quantity', '>=', 50)
    ->orWhen('total', '>=', 500)
    ->then(fn () => ['discount' => 0.1])
    ->build()
    ->evaluate(['role' => 'vip', 'total' => 150, 'quantity' => 10]);

Negated Conditions

$engine = RuleEngine::create()
    ->rule('active-non-banned')
    ->when('active', '=', true)
    ->notWhen('status', '=', 'banned')
    ->then(fn () => 'access granted')
    ->build();

Priority and Stop-on-Match

$engine = RuleEngine::create()
    ->rule('high-priority')
    ->when('value', '>', 0)
    ->then(fn () => 'important')
    ->priority(10)
    ->stopOnMatch()
    ->build()
    ->rule('low-priority')
    ->when('value', '>', 0)
    ->then(fn () => 'fallback')
    ->priority(1)
    ->build();

$result = $engine->evaluate(['value' => 5]);
// Only 'high-priority' matches because stopOnMatch is set

First Match Only

$result = $engine->evaluateFirst(['value' => 5]);
// Returns a single RuleResult or null

Nested Context with Dot Notation

$result = RuleEngine::create()
    ->rule('city-check')
    ->when('user.address.city', '=', 'Vienna')
    ->then(fn () => 'local')
    ->build()
    ->evaluate([
        'user' => [
            'address' => ['city' => 'Vienna'],
        ],
    ]);

Compiled Rule Engine

$compiled = RuleEngine::create()
    ->rule('adult')
    ->when('age', '>=', 18)
    ->then(fn () => 'allowed')
    ->build()
    ->compile();

// Evaluate multiple contexts with pre-compiled closures
$result = $compiled->evaluate(['age' => 25]);
$first = $compiled->evaluateFirst(['age' => 25]);

Audit Mode

$result = RuleEngine::create()
    ->rule('a')
    ->when('x', '>', 0)
    ->then(fn () => 'matched')
    ->build()
    ->withAudit()
    ->evaluate(['x' => 5]);

$result->auditEntries(); // Array of AuditEntry objects
$result->evaluatedCount(); // Number of rules evaluated
$result->skippedCount(); // Number of rules skipped

Rule Validation

$engine = RuleEngine::create();
$engine->addRule(new Rule('no-conditions', [], fn () => 'x'));

$warnings = $engine->validate();
// ["Rule 'no-conditions' has no conditions and will always match."]

Custom Context Accessor

Implement ContextAccessor to read values from any data structure:

use PhilipRehberger\RuleEngine\Contracts\ContextAccessor;

class EloquentAccessor implements ContextAccessor
{
    public function get(mixed $context, string $path): mixed
    {
        return data_get($context, $path);
    }

    public function has(mixed $context, string $path): bool
    {
        return data_get($context, $path) !== null;
    }
}

$engine = RuleEngine::create(new EloquentAccessor());

API

RuleEngine

RuleBuilder

CompiledRuleEngine

Operators

EvaluationResult

AuditResult (extends EvaluationResult)

RuleResult

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT