Download the PHP package leeovery/rules-engine without Composer

A rule set is a named, ordered list of rules, and each rule has a key, a condition and a value. You resolve a rule set against facts, and the best-matching rule answers.

Rule sets are stored as immutable versions. Every change publishes the next version, and nothing is ever edited or deleted. Each rule keeps a permanent uuid across versions, and every match says which version and rule answered, so a decision can be explained and reproduced later.

Why Rules Engine?

Business rules change more often than code: which category a merchant belongs to, which rate applies from April, which queue a request goes to. Hard-code them and every change needs a deploy. Keep them in a plain table and every change overwrites the old answer, so nobody can say later why a decision came out the way it did.

• Every answer can be explained. A match names the version and the rule that answered, by a uuid that survives updates, moves and renames.
• Nothing is overwritten. Every publish writes a new, immutable version, so a past lookup can be run again exactly as it was.
• Dates are built in. A version can take effect on a date, so next April's rates can be published today, and a correction to last year changes last year only.
• Changes are safe and visible. Edits name rules by key and apply under a row lock, preview() shows a change before it's made, and every publish fires an event listing what changed, rule by rule.

Install

The service provider and the RulesEngine facade register themselves. The migrations run from the package, so there's nothing to publish. They create three tables, rule_sets, rule_set_versions and rules:

Publish the config file if you want to change the cache settings:

Requirements

• PHP 8.4+
• Laravel 13

Quick Start

Core Concepts

• Rule sets are named by a string or a backed enum, and hold an ordered list of rules. A set is created the first time it's published.
• Versions are immutable, and can be dated. Each publish writes the next version, numbered 1, 2, 3…, holding the complete rule list, and nothing is ever updated or deleted. A version can carry an effective date. Every lookup is as of a date and sees only the versions published by a moment, so a past lookup can be reproduced. See effective dates.
• Rules have a key and a uuid. The key names a rule within a version, and it's how you edit the rule. The uuid is its permanent identity: it survives updates, moves and renames, and every match carries it.
• Conditions are tested against facts. Conditions are built like a query builder's where() clauses and stored as JSON. Resolving scores each rule's condition against the facts you pass: the most specific match wins, and position breaks ties. See scoring and ties.
• Publish a list, or edit by key. Publish a complete list of rules, or edits to the version in force: addRule(), updateRule(), moveRule(), renameRule() and removeRule(). Publishing refuses anything ambiguous, such as two rules sharing a key or a condition. See changing rules.
• Preview and revert. preview() works out what a publish would do without doing it, and revertTo() publishes an earlier version's rules again as the next version.
• Every publish announces its changes. RuleSetVersionPublished fires inside the publishing transaction, carrying the rules added, removed, renamed and moved, and those whose condition, value or metadata changed. See events.
• Matches are cached. They're keyed by version and facts, and versions never change, so a cached match never goes stale. Choosing the version is never cached, so a new version takes effect at once.
• Publishing locks the rule set. Concurrent publishes of one set queue on its row, number their versions in turn, and apply their edits on top of each other rather than overwriting them. See changing rules for how this works on SQLite.

Reference

Publishing a Rule Set

The examples below follow one rule set, which sorts card transactions into spending categories by merchant. Name rule sets with a backed enum, or plain strings:

Publish the first version as a complete list of rules:

publish() stores version 1 and returns it as a RuleSetVersion with its rules loaded.

• Keys name rules within a version, and must be unique in it. Every key argument takes a backed enum as well as a string, and an enum is stored as its value.
• Positions follow the order of the list, starting at 1, and break ties between equally good matches.
• Values are stored as JSON. Arrays, scalars and null are fine, a backed enum is stored as its value, and closures and other objects are refused. Metadata, the optional fourth argument, is JSON too.
• Uuids are UUIDv7s, given to each rule when it first appears.
• The description is used when the set is first created.

Publishing a complete list again creates the next version, holding exactly the rules listed. A rule keeps the uuid of the previous version's rule with the same key, and a new key gets a new uuid.

The facade stands for LeeOvery\RulesEngine\RulesEngine, which you can inject instead.

Resolving

A RuleMatch is a readonly value that says what answered:

Add facts as an array or a key and value. Calling with() again adds to them, and a later fact replaces an earlier one with the same key. Backed enums in facts are compared by their values, the same way they're stored in conditions.

Changing Rules

Instead of listing every rule again, publish edits to the version in force. Edits name rules by key:

One publish can carry several edits, applied in order:

Edits are applied when you publish, under a lock on the rule set, to whatever version is current then. If someone else publishes in between, both changes land: yours are applied on top of theirs. Publishes of one set queue on that lock and number their versions in turn.

The lock is a SELECT … FOR UPDATE on the rule set's row. SQLite has no row locks, so Laravel leaves the lock out there. SQLite lets only one transaction write at a time, so there a publish that races another fails instead of queueing, and never overwrites it.

A rule's uuid never changes while the rule exists, through any number of updates, moves and renames. A key that's removed and later added again is a new rule with a new uuid.

A builder publishes either a complete list or edits, not both.

Previewing a Change

preview() works out what a publish would do, without publishing it or firing anything:

It refuses whatever publishing would refuse.

Reverting

revertTo() publishes a copy of an earlier version's rules, with the same keys and uuids, as the next version:

It can't be combined with a list or edits. A version that doesn't exist throws NoApplicableVersionException. In a dated set, the copy needs an effective date of its own, as any new version does: ->effectiveFrom('2027-04-06')->revertTo(1).

Seeing What Changed

RuleSetChanges compares two versions rule by rule, matching rules by uuid:

moved lists the fewest rules whose moves give the new order, so adding or removing a rule doesn't count the rules around it as moved. Values and metadata are compared as they're stored.

Every published version carries its changes from the version it follows, in its event. For version 1, every rule is added.

As of a Date, as Known at a Moment

Every lookup is as of a date, today unless you pass asOf(), and considers only versions published at or before a moment, now unless you pass knownAt():

• The version in force on a date is the one with the greatest effective date on or before it, and among those, the highest version number. A version without an effective date is in force from the start, below any dated version. Merchant categories have no effective dates, so their newest version is always in force, whatever the date.
• asOf() takes a DateTimeInterface or a string, and reads the date in the value's own timezone.
• knownAt() reproduces a lookup as it was at a moment, to the microsecond, in any timezone. It defaults to now, so versions published after the current time are invisible: a test that travels back in time needs its versions published by then, or an explicit knownAt().
• atVersion(3) pins an exact version, whatever asOf and knownAt say, for re-scoring history.

Choosing the version is a small query that's never cached, so a new version takes effect at once. If no version applies, the lookup throws NoApplicableVersionException, naming the date and moment it looked for. An unknown rule set throws RuleSetNotFoundException.

Effective Dates

Reference data such as tax rates changes on known dates. Give its versions effective dates. With a UkDividendRates = 'uk.dividend-rates' case on the enum:

• A set's first version decides. If it has an effective date, every later version needs one. If it doesn't, none may have one.
• Effective dates are calendar dates, given as a DateTimeInterface or a string. A DateTimeInterface keeps the date in its own timezone.
• No version can take effect before the first version's date. A later version can take effect on an earlier date than the newest, which corrects that period: it replaces what was in force from its date until the next dated version.
• A new version follows the version in force on its effective date. Edits apply to that version, and changes are measured from it, so a correction for last year edits last year's rates, not this year's.

What Publishing Refuses

Publishing throws CannotPublishRuleSetException, and stores nothing, when:

• there are no rules;
• two rules share a key;
• two rules share a condition, since the second could never be chosen first;
• a value, metadata or condition holds something JSON can't store;
• an effective date breaks the first version's choice, or comes before its date;
• an edit refers to a missing rule, or would reuse a taken key.

Mixing a list and edits, or a revert with either, throws straight away, and so do an addRule() with both before and after, a moveRule() without exactly one of them, and an updateRule() with nothing to change.

Events

Publishing runs in one database transaction and dispatches LeeOvery\RulesEngine\Events\RuleSetVersionPublished inside it, after the version is written and before the transaction commits. The event carries ruleSet (the name), version, effectiveFrom, publishedBy, note and changes, the RuleSetChanges from the version it follows.

The event doesn't wait for the commit: listeners run inside the transaction, and if one throws, the version is rolled back. A queued listener's job is pushed at once too, unless the listener or its queue connection waits for commits (after_commit). On a database queue on the same connection, a job pushed at once is written in the same transaction as the version, so neither lands without the other.

Immutability

RuleSetVersion and Rule models throw ImmutableRecordException when you update, increment or delete them, including the quiet variants and while model events are faked. A rule set that has versions can't be deleted either: the foreign keys restrict it.

Building Conditions

Conditions use a fluent API modelled on Laravel's query builder.

Clauses combine from left to right. Without nesting, ->orWhere() applies to the whole condition chain before it, and a ->where() after it applies to the whole result, so where('a', 1)->orWhere('b', 2)->where('c', 3) means (a or b) and c. Nest a closure to group clauses any other way.

Equality and in are strict, so 1 doesn't equal '1', and true doesn't equal 1. >, >=, < and <= use PHP's comparison operators, and contains, starts_with and ends_with compare case-sensitive strings. A condition on a fact that isn't there doesn't match, not even whereNull() or whereNotIn().

Scoring and Ties

The engine scores matches with MAX-CSP (maximum constraint satisfaction): a match scores the number of clauses satisfied along the most specific way its condition matched. Clauses combine from left to right, as in building conditions:

• a clause scores 1 when it matches, and 0 when it doesn't;
• an AND scores the sum of its two sides when both match; when either side fails, the AND fails and scores 0, however many of its clauses matched;
• an OR scores the higher of the sides that matched, so a side that failed adds nothing;
• a nested group is scored the same way, as one side;
• Condition::always() matches with a score of 0.

So where('a', 1)->where('b', 2)->where('c', 3)->orWhere('d', 4) scores 3 when a, b and c match, whether or not d does, and 1 when d matches but c doesn't, even if a and b do.

Matches are ordered by score, highest first, so the most specific matching rule wins. Equal scores are ordered by position, lowest first, so ties never depend on database order.

Caching

Matches are cached for the configured time, keyed by the version's id and the facts. Versions never change, so a cached result never goes stale, and a new version is used as soon as it's published.

cache() takes a number of seconds greater than zero. The defaults live in the config file:

Matches are cached as plain arrays, so they work with Laravel 13's default cache.serializable_classes => false.

Reading History

A RuleSetVersion has version, effective_from (a CarbonImmutable date or null), published_at (a CarbonImmutable with microseconds), published_by, note, and its ruleSet and rules, ordered by position.

Database Schema

rule_sets

rule_set_versions

rules

Testing

The suite runs on SQLite by default. Postgres is the only database that lets the row-locking tests hold a lock from a second session, so they're skipped elsewhere. Point the suite at a Postgres database to run them:

CI runs the suite on SQLite and on Postgres 17, with PHP 8.4 and 8.5, against the lowest and the newest dependencies.

Changelog

See CHANGELOG.md.

License

MIT. See LICENSE.md.