Download the PHP package prohalexey/the-choice without Composer

TheChoice - Business Rule Engine

A powerful and flexible Business Rule Engine for PHP that allows you to separate business logic from your application code.

Features

This library helps you simplify the implementation of complex business rules such as:

• Complex discount calculations
• Customer bonus systems
• User permission resolution
• Dynamic pricing strategies

Why use TheChoice? If you find yourself constantly modifying business conditions in your code, this library allows you to move those conditions to external configuration sources. You can even create a web interface to edit configurations dynamically.

Key Benefits

• ✅ Rules written in JSON or YAML format
• ✅ Store rules in files or databases
• ✅ Serializable and cacheable configurations (PSR-16)
• ✅ PSR-11 compatible container support
• ✅ Extensible with custom operators and contexts
• ✅ Rule Engine — evaluate multiple rules in a single run
• ✅ Rule Registry — named rules with tags, version, and metadata
• ✅ Rule Validator — static analysis of rules before execution
• ✅ Evaluation Trace — step-by-step debugging of rule evaluation
• ✅ Event System — PSR-14 lifecycle and node-level events for observability
• ✅ Switch Node — multi-branch dispatch on a single context value
• ✅ Fluent PHP Builder (DSL) — build rule trees programmatically without JSON/YAML
• ✅ Node Exporter — serialize rule trees back to JSON or YAML
• ✅ Storage variable references — use $storageKey as operator values

Table of Contents

• Installation
• Quick Start
• Configuration Formats
  • JSON
  • YAML
• Core Concepts
  • Node Types — Root, Value, Context, Condition, Collection, Switch
  • Built-in Operators
  • Modifiers
  • Storage Variable References
• Rule Engine — multi-rule evaluation
• Rule Registry — named rules with metadata
• Rule Validator — static analysis / linter
• Evaluation Trace — debugging
• Event System — PSR-14 lifecycle & node events
• Caching — PSR-16
• Container Integration — Built-in & Symfony
• Advanced Features — custom contexts, operators, processor flushing
• Fluent Builder (DSL) — build rules in PHP without JSON/YAML
• Node Exporter — serialize rule trees to JSON or YAML
• License

Installation

Requirements: PHP 8.4+

Quick Start

Configuration Formats

JSON Configuration Example

YAML Configuration Example

Core Concepts

Node Types

Each node has a node property that describes its type and an optional description property for UI purposes.

Root Node

The root of the rules tree that maintains state and stores execution results. When the root node is omitted in the configuration, the library automatically wraps the top-level node in a root node (short syntax).

Properties:

• storage - Named variables accessible in modifier expressions and as operator value references (e.g. $myVar). Values are resolved at parse time.
• rules - Contains the first node to be processed

Example:

Value Node

Returns a static value.

Properties:

• value - The value to return (can be array, string, or numeric)

Example:

Context Node

Executes callable objects and can modify the global state which is stored in the "Root" node.

Properties:

• break - Special property to stop execution early. When set to "immediately", the context result is saved to the Root node and evaluation stops — subsequent nodes in a collection are skipped. The final result is retrieved from the Root node.
• context - Name of the context for calculations
• modifiers - Array of mathematical modifiers
• operator - Operator for calculations or comparisons
• params - Parameters to set in context
• priority - Priority for collection sorting
• value - Value to compare against when using an operator. Can be a literal (0, "admin", [1,100]) or a $storageKey reference (resolved from Root storage at parse time).

Example:

With Operator Example:

With Break Example:

Condition Node

Conditional logic with if-then-else structure.

Properties:

• if - Condition node (expects boolean result)
• then - Node to execute if condition is true
• else - Node to execute if condition is false (optional)

Example:

Collection Node

Contains multiple child nodes evaluated with a chosen logical strategy.

Properties:

• type - Collection type: and, or, not, atLeast, or exactly
• nodes - Array of child nodes
• count - Required for atLeast and exactly types; specifies the threshold
• priority - Priority used when this collection is nested inside another collection

Type reference:

and Example:

not Example — passes when the user is not blacklisted:

atLeast Example — passes when at least 2 out of 3 conditions are met:

exactly Example — passes when exactly 2 conditions are met:

Switch Node

Evaluates a single context value once and routes execution to the first matching case branch. Similar to a switch/case statement in PHP, but the match criterion for each case can be any registered operator (not just equality).

Properties:

• context — name of the context to evaluate (resolved once)
• cases — array of case entries, each containing:
  • value — the value to compare against
  • operator — (optional) operator name; defaults to equal
  • then — any node to execute when this case matches
• default — (optional) any node to execute when no case matches; returns null when omitted

Cases are evaluated in order and the first match wins — subsequent cases are skipped.

Basic example (role-based dispatch):

Range dispatch with operators (first match wins):

JSON equivalent:

The then and default branches can be any node type — including context (with modifiers), condition, collection, or even a nested switch:

Built-in Operators

The following operators are available for context nodes:

Equality & comparison

• equal — Strict equality (===)
• notEqual — Strict inequality (!==)
• greaterThan — Greater than comparison
• greaterThanOrEqual — Greater than or equal
• lowerThan — Less than comparison
• lowerThanOrEqual — Less than or equal
• numericInRange — Number within an inclusive range; value must be a two-element array [min, max]

String

• stringContain — String contains substring
• stringNotContain — String does not contain substring
• startsWith — String starts with prefix
• endsWith — String ends with suffix
• matchesRegex — String matches a PCRE regex pattern (e.g. "/^\d{4}$/")

Array

• arrayContain — Array contains the given element (strict)
• arrayNotContain — Array does not contain the given element (strict)
• containsKey — Array contains the given key (string or int)
• countEqual — Number of array elements equals value
• countGreaterThan — Number of array elements is greater than value

Type checks (no value field required)

• isEmpty — Value is null, empty string "", or empty array []
• isNull — Value is strictly null
• isInstanceOf — Object is an instance of the given fully-qualified class name

Modifiers

Modifiers allow you to transform context values using mathematical expressions. Use the predefined $context variable in your expressions. Variables defined in the Root storage are also available.

For more information about calculations, see: https://github.com/chriskonnertz/string-calc

Storage Variable References

Any string starting with $ in an operator's value field (or a Switch case value) is resolved against Root storage at parse time. This lets you centralise thresholds and constants in one place and reference them across rules:

Works equally in Switch cases:

Resolution rules:

Storage variables continue to work in modifiers exactly as before — the two features are independent and composable.

Rule Engine

RuleEngine evaluates multiple rules in a single run() call and returns an EngineReport with the result of each rule. Rules are executed in priority order (highest first).

A rule is considered fired when its result is neither null nor false.

Rule Registry

RuleRegistry is a named storage for rules with tags, version, and description metadata.

Rule Validator

RuleValidator performs static analysis of a rule tree before execution — it checks that all referenced contexts and operators are registered. Unknown names produce helpful "did you mean?" suggestions based on Levenshtein distance. This is useful in CI/CD pipelines to catch configuration errors before deployment.

Each ValidationError contains:

• message — human-readable error description
• path — location in the tree (e.g. root > rules > condition.if > collection[1])
• suggestion — closest valid name if the Levenshtein distance is ≤ 3, or null

Pass empty arrays to skip validation of contexts or operators:

The ValidationException provides programmatic access to errors:

Evaluation Trace

RootProcessor::processWithTrace() runs the rule tree with tracing enabled. It returns an EvaluationTrace that contains both the final result and a detailed tree of every node visited during evaluation — which node was entered, what it returned, and the nesting structure.

Programmatic Trace Access

The trace is a tree of TraceEntry objects that you can walk programmatically:

Result Formatting

TraceEntry::toString() formats results in a human-readable way:

Zero Overhead

Tracing has zero overhead when not used — the trace collector is only active during processWithTrace() and is automatically cleaned up afterwards. A normal process() call is completely unaffected.

Event System

RuleEngine accepts an optional PSR-14 EventDispatcherInterface and dispatches events at key points during evaluation. Events are purely observational — they do not alter rule results.

Available Events

Using with RootProcessor directly

You can also attach the dispatcher to RootProcessor for standalone rule evaluation (without RuleEngine):

Events work alongside processWithTrace() — both systems are independent.

Zero Overhead

Events have zero overhead when no dispatcher is set — all dispatch calls are guarded by null checks.

Caching

CachedJsonBuilder and CachedYamlBuilder wrap the base builders with a transparent PSR-16 cache layer. The node tree is serialized after the first parse and deserialized on subsequent calls; the cache key is derived from the MD5 of the rule content, so the cache is automatically invalidated when the content changes.

CachedYamlBuilder works identically — just substitute CachedYamlBuilder for CachedJsonBuilder.

Container Integration

Built-in Container

TheChoice\Container is a small PSR-11 implementation bundled with the library. It is intended as a fallback for plain PHP projects without a DI container.

You can extend it at runtime without modifying library code:

You can also override built-in services (for example, a default resolver):

Using Symfony Container

The library is PSR-11 compatible and works with Symfony DI.

For complete Symfony examples (compact setup + explicit setup, JsonBuilder and YamlBuilder services), see:

• docs/symfony.md

Advanced Features

Custom Contexts

Create custom context classes by implementing ContextInterface and register them in the container:

Custom Operators

Create custom operators by extending AbstractOperator and registering the mapping via OperatorResolverInterface::register():

For Symfony examples (register() through DI calls), see docs/symfony.md.

Processor Cache Flushing

Each call to RootProcessor::process() automatically calls flush() on all registered processors, clearing any memoised results from the previous evaluation. This ensures correctness when the same processor instance is reused across multiple rule evaluations.

Examples and Testing

For more detailed examples and usage patterns, see the test files in the test/ directory, especially the container configuration examples.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fluent Builder (DSL)

RuleBuilder provides a fluent PHP API for building rule trees programmatically — without writing JSON or YAML. All builders are immutable after construction and materialise their corresponding Node on the final ->build() call.

Always wrap the outermost builder in RuleBuilder::root() — its build() propagates the Root reference to every child node, which is required by modifiers, stoppable contexts, and the Switch processor.

Full Example

Static Entry Points

ContextBuilder

All 20 built-in operators are available as typed methods:

Additional configuration:

CollectionBuilder

Available types: and, or, not, atLeast (requires ->count(n)), exactly (requires ->count(n)).

SwitchBuilder

RootBuilder

Node Exporter

JsonNodeExporter and YamlNodeExporter convert a Node tree back to a JSON or YAML string (or file). The output is round-trip safe — re-parsing the exported content produces a tree with identical runtime behaviour.

Both exporters share the same NodeSerializer which builds the intermediate PHP array.

The NodeSerializer intermediate toArray() is public — use it directly when you need the raw PHP array:

Round-trip guarantee: all built-in node types (Root, Value, Context, Condition, Collection, SwitchNode) are fully supported. Optional fields (description, priority, params, modifiers, storage, break, else, default) are only emitted when they differ from the default value, keeping the output minimal.

License

This project is licensed under the MIT License - see the LICENSE file for details.