Download the PHP package yl0711-coder/ruleflow-php without Composer

RuleFlow PHP

简体中文

A lightweight Decision List rule engine for PHP and Laravel.

RuleFlow helps backend teams move complex business rules out of hard-coded if/else logic and into testable, configurable, and traceable rule definitions.

It is designed for risk control, content moderation, marketing eligibility, access control, and business decision workflows.

Why This Project Exists

Many PHP systems start with a few inline checks:

That works until the rules become:

• scattered across controllers, services, jobs, and listeners
• hard to validate before deployment
• hard to explain to support, operations, or reviewers
• risky to change because business logic is mixed with application flow

RuleFlow keeps the model intentionally small:

• it uses a Decision List model: deterministic priority order, first matching decision by default
• rules are structured data, not framework-specific code
• evaluation is deterministic and priority-based
• decisions can be inspected with trace() or summarized with explain()
• Laravel integration exists, but the core stays framework-agnostic

RuleFlow is not a RETE inference engine. It is for PHP business decisions where the problem is scattered rules, unsafe changes, and unclear explanations rather than working-memory inference or complex event processing.

What You Get

• First-match and all-match evaluation with evaluate() and evaluateAll()
• Nested condition groups such as A AND (B OR C)
• Built-in operators for equality, numeric checks, arrays, existence, strings, and regex
• Rule validation before runtime
• Trace diagnostics with failure reasons and timing
• Compact explain() output for APIs, logs, and support tools
• Sensitive-value redaction with sensitive: true
• Optional rule metadata for ownership, versions, tickets, and rollout notes
• Laravel config loading, cache support, and php artisan ruleflow:validate

Good Fit

RuleFlow is a good fit when you need:

• order or payment risk decisions
• content moderation routing
• campaign or coupon eligibility checks
• access-control decisions with request context
• business rules that need to be reviewed, tested, and explained

It is not trying to be:

• a visual rule builder
• a BPMN or workflow platform
• a distributed decision service
• a replacement for full policy, validation, or workflow systems

Why Not A Heavy Rule Engine

Many teams do not need a full decision platform. They need a small library that can live inside an existing PHP service and solve one practical problem: replace scattered conditional business logic with something structured, testable, and explainable.

RuleFlow is intentionally optimized for that use case:

• no external server to run
• no DSL or visual designer to learn
• no database schema required
• no framework lock-in for core usage
• no large integration surface before the first useful rule ships

Compared with heavier rule engines, RuleFlow trades breadth for clarity:

• fewer concepts to learn
• faster adoption inside an existing Laravel or PHP codebase
• easier code review because rules stay close to application context
• easier production debugging because trace() and explain() are built in

If your problem is "we need a rules platform", RuleFlow is probably too small. If your problem is "our PHP business logic is turning into untestable if/else sprawl", RuleFlow is the right size.

Project Status

Current release line: v0.3.x

The project already includes:

• Packagist distribution
• CI with PHPUnit, PHPCS, PHPStan, examples, and install validation
• changelog and GitHub Release flow
• production, security, and Laravel documentation

Installation

Via Packagist

From GitHub VCS

The package requires PHP 8.1 or later.

Quick Start

JSON Rules

Rules can also be stored as JSON and loaded at runtime:

See examples/json-loader.php.

Documentation

Start here:

• docs/README.md
• docs/decision-list-model.md
• docs/quickstart.md
• docs/rule-format.md
• docs/semantics.md

Operational usage:

• docs/explain.md
• docs/production.md
• docs/security-privacy.md

Laravel:

• docs/laravel.md
• docs/laravel-compatibility.md
• docs/laravel-installation.md
• docs/laravel-example.md

Trace Output

RuleFlow returns a trace so engineers, support teams, and reviewers can understand why a rule matched.

Example output:

When a field does not exist, the trace explicitly marks it with exists: false and missing: true. Disabled rules are marked with skipped: true and skipped_reason: "disabled".

When a rule or condition fails, RuleFlow includes failure_reason when it can infer one. Examples include field_missing, type_mismatch, invalid_expected, value_mismatch, value_not_allowed, value_not_contained, and pattern_mismatch.

When a condition is marked with sensitive: true, RuleFlow redacts actual and expected values in trace and explain output as [redacted].

You can also use trace helpers for operational debugging:

Explain Output

Use explain() when you want a compact decision summary for logs, API responses, or support tooling:

Example output:

trace() keeps the full execution detail. explain() keeps the decision summary small and stable for operational use.

See docs/production.md, docs/security-privacy.md, and examples/explain.php.

Supported Operators

RuleFlow supports:

• =
• !=
• >
• >=
• <
• <=
• in
• not_in
• exists
• not_exists
• contains
• starts_with
• ends_with
• between
• regex

= and != use strict PHP comparison semantics (=== / !==).

See docs/semantics.md for the full evaluation contract.

Match Modes

Each rule supports a match mode:

• all: every condition must pass. This is the default.
• any: at least one condition must pass.

Example:

Nested Condition Groups

RuleFlow also supports nested condition groups for cases like A AND (B OR C):

Nested groups are evaluated recursively and included in the execution trace.

Collect All Matches

Use evaluateAll() when you need every matched rule instead of only the first one:

This is useful for risk scoring, moderation signals, and rule-based tagging scenarios.

Custom Operators

Register a custom operator when built-in operators are not enough:

Rule Validation

Validate rule definitions before loading them:

See docs/validation.md.

Laravel Usage

Publish the config:

Define rules in config/ruleflow.php:

Optional cache settings:

Evaluate rules:

The context accepts nested arrays, public object properties, ArrayAccess offsets, and magic __isset/__get accessors — so Eloquent models can be passed directly, for example ['order' => $order].

Validate configured rules:

See docs/laravel.md, docs/laravel-installation.md, and docs/laravel-example.md.

Use Cases

• Risk control: reject or review suspicious orders, users, or API requests.
• Content moderation: route posts, comments, and profiles to review queues.
• Marketing eligibility: decide whether a user can receive a coupon or campaign.
• Access control: evaluate contextual access decisions.
• Business workflow: choose approval paths from structured business conditions.

Non-Goals

RuleFlow is intentionally small. The first versions do not aim to provide:

• a visual rule management UI
• a distributed decision platform
• a full workflow engine
• database migrations or admin dashboards
• replacement for Laravel policies, gates, or validation

Development

Run examples:

Generate coverage locally when Xdebug or PCOV is available:

Run the local benchmark:

See docs/benchmark.md.

For production usage recommendations, see docs/production.md.

Roadmap

• v0.1: core engine, built-in operators, trace output, array/JSON loaders, custom operators, rule validation
• v0.2: nested rule groups, evaluateAll, existence operators, built-in regex, trace improvements, Laravel cache driver, artisan validation command, PHPStan, coverage CI
• v0.3: richer trace diagnostics, failure reasons, compact explain output, benchmark suite, production and security guidance
• v0.4: documentation polish, more production examples, API refinement, and ecosystem hardening
• v1.0: stable rule format and semantic versioning guarantee

License

RuleFlow PHP is open-sourced software licensed under the MIT license.