Download the PHP package mathiasonea/laravel-rulebook without Composer

Laravel Rulebook

Keep historical business decisions reproducible—even after the rules change.

Pricing, eligibility, and entitlement rules often change on a specific date. When that logic lives in growing if statements, it becomes difficult to answer:

• Which rule applied to this invoice, quote, or customer?
• Why did that rule win?
• Would the same decision be reproduced for that date?

Give each policy version a name and validity period. When resolution succeeds, Laravel Rulebook returns one explicit winner for that point in time:

The same decision also explains what happened to every other rule:

Change tomorrow's policy without rewriting yesterday's decision.

Before and after

Without an explicit model, effective-date logic tends to grow inside one branching path:

With Rulebook, each policy version remains a named rule. The decision date is explicit, and the result says which rule won and why:

Every resolution also retains the complete evaluation: applicable fallbacks, rejected rules, and rules skipped because they were outside their validity window.

Installation

Laravel discovers the package provider automatically. There is no configuration to publish, migration to run, facade, or global registry.

For a complete working application, run the Austrian EV pricing example. It compares three yearly policies and prints the winner, fallbacks, skipped validity windows, and reasons from one Artisan command.

Use it when

• Effective-date conditionals keep accumulating in application services.
• A policy is edited in place even though old decisions must remain reproducible.
• Several rules can apply and the intended winner or fallback must be explicit.
• A decision varies by subject, context, and point in time.
• You need to reconstruct why an invoice, price, entitlement, or eligibility decision was made.

Requirements

• PHP 8.3 or newer
• Laravel 12 or 13

Not a fit when

Rulebook is deliberately code-defined and resolves exactly one winning rule. It is not a fit when you need:

• A DSL or rules authored in a database or UI.
• Workflow or state-machine behavior.
• Outcomes composed from multiple winning rules.

Resources

• Project page — the permanent overview of Laravel Rulebook.
• Architecture guide — a practical explanation of replacing dated conditionals with auditable, versioned rules.
• Runnable Austrian EV example — a focused Laravel 12 application comparing the 2025, 2026, and 2027 policies, including fallbacks and skipped validity windows.

Versioned pricing in practice

Suppose an Austrian electric-vehicle price changes every calendar year. The base price, incentive, and battery fee can all change, while a general Austrian price and a global default must remain available as fallbacks.

Model each policy version as its own rule. The rulebook then becomes a readable history of every policy that can govern the decision:

The PHPStan annotation establishes the subject, context, and outcome types for every rule in the rulebook. Rule order does not decide the winner; every applicable rule participates in explicit priority resolution.

Share stable policy, isolate yearly changes

Common eligibility can live in an abstract application-owned rule. The calculation delegates the values that are expected to change to the concrete yearly policy:

Each year supplies its own validity window and parameters:

This keeps a historical policy intact after a new year begins. If the formula itself changes in 2027—not just its parameters—the 2027 class can override the calculation without adding if ($year === ...) branches to older rules.

The rule class strings are resolved through Laravel's container, so the shared rule or concrete yearly rules can use constructor injection without package-specific registration. Exceptions from a rule or one of its dependencies bubble unchanged; an operational failure is never converted into “does not apply.”

Resolve and inspect a dated decision

Resolve historical or future decisions with a DateTimeInterface:

At that instant, the 2025 and 2027 rules are outside their validity windows and are not invoked. The 2026 rule wins with priority 100; the general Austrian and default prices can still be inspected as applicable but shadowed fallbacks.

The same rulebook can reproduce decisions under earlier or later policy versions without changing application code:

The returned decision exposes the winner and the complete evaluation:

A lower-priority match is still applicable. It is described as shadowed because the sole higher-priority rule governs the decision.

Evaluate without requiring a winner

Use evaluateNow() or evaluateAt() when diagnostics must remain available even if no rule applies or the top priority is ambiguous.

resolveNow() and resolveAt() are convenience methods for evaluating and then resolving.

Resolution throws:

• NoMatchingRule when nothing applies.
• AmbiguousRuleMatch when more than one applicable rule shares the highest priority.
• DuplicateRuleKey when registered rules expose the same key.
• InvalidRuleKey when a registered rule exposes a blank key.

NoMatchingRule and AmbiguousRuleMatch both retain the exact Evaluation on their public $evaluation property and through evaluation(). Registration order never breaks an equal-priority tie.

Rule authoring contract

Rulebook evaluates every rule inside its validity period, including lower-priority fallbacks, so that the returned evaluation explains the complete decision. Treat evaluate() as a deterministic, side-effect-free operation:

• Use $input->at instead of reading the current clock inside a rule.
• Do not send messages, write data, or trigger other side effects from evaluate().
• Keep key(), priority(), and validity() stable for the lifetime of an evaluation.
• Make reasons safe and useful for logs or other diagnostic output.
• Let operational failures bubble; do not convert exceptions into domain-level rejections.
• Account for mutable dependencies: resolving an old date reproduces the policy represented by the currently deployed code and data, not necessarily the exact historical execution.

The default rule key is its class name. That is convenient while developing, but a class rename changes the key. Override key() with a stable domain identifier when decisions or their explanations are stored outside the current request:

Rulebook returns the complete evaluation but deliberately does not persist it. Applications that require a durable audit record can store a portable snapshot alongside their own business record.

Structured statuses and reason codes

Every RuleEvaluation has one structured status:

• RuleEvaluationStatus::Applicable when the rule produced an applicable result.
• RuleEvaluationStatus::DoesNotApply when the rule was evaluated but did not apply.
• RuleEvaluationStatus::OutsideValidity when the rule was skipped because of its validity period.

wasEvaluated() remains available when only the distinction between a domain rejection and a skipped rule matters. Rule keys, priorities, and validity periods are captured once before domain evaluation, so later inspection cannot change the winner.

Results may also include an optional machine-readable reason code alongside the mandatory human explanation:

Use reason codes for stable filtering, metrics, or localization; keep the reason useful to a human reading the decision.

Portable decision snapshots

Snapshots remove live subject, context, and rule objects while retaining the decision time, frozen rule metadata, validity windows, statuses, reasons, and reason codes. A decision snapshot always has one winner; an evaluation snapshot can instead record a conflict or no match. Both implement JsonSerializable and expose toArray():

Scalar, array, backed-enum, or JsonSerializable outcomes can use $decision->snapshot() directly. Supply normalizeOutcome when another outcome object needs an application-specific portable representation. Snapshot creation eagerly copies the normalized value and throws UnportableSnapshotValue for unsupported objects, resources, invalid UTF-8, non-finite numbers, cycles, or excessive nesting.

An evaluation can be snapshotted before resolution, including when no rule applies or several rules conflict:

Snapshots are transport records, not persistence. The application remains responsible for choosing where to store them and which subject or business-record identifier belongs beside them.

Every top-level snapshot contains schema_version: 1. The serialized field names, meanings, and status values are public API and follow the package's semantic-versioning policy.

Validity periods

Periods are half-open: [from, until).

• from is inclusive.
• until is exclusive.
• Open starts and ends are supported.
• Empty and reversed periods throw InvalidValidityPeriod.
• Inputs are copied into immutable date-time values.
• Comparisons use absolute instants; timezones are never silently rewritten.

An out-of-window rule is not invoked. Its RuleEvaluation is inapplicable, has a generated validity reason, and returns false from wasEvaluated().

Optional context

Use null as the context type when a decision only needs its subject:

RuleInput::subject() and RuleInput::context() provide typed access. A mismatch throws UnexpectedSubject or UnexpectedContext with the expected and actual types.

Nullable outcomes

null can be a valid typed outcome:

Applicability is stored separately from the outcome, so this is not confused with RuleResult::doesNotApply(...).

Time and testing

“Now” resolutions use Carbon's clock, including CarbonImmutable::setTestNow() in tests. Explicit DateTimeInterface values passed to resolveAt() and evaluateAt() are copied without changing their instant.

Roadmap

• First-party temporal test matrices and expressive decision assertions
• Inspection tooling for keys, priorities, validity windows, gaps, and obvious collisions
• Optional Laravel integrations for observing or persisting snapshots
• Further extension points driven by concrete production use cases

Already maintaining effective-date business logic? Model one real decision with Rulebook, then open an issue or start a discussion and tell us where the API feels heavy or breaks down. Focused pull requests are welcome; please discuss larger changes first.

Core invariants

Blank reasons, blank provided reason codes, blank rule keys, and invalid or empty validity periods are rejected. Skipped out-of-window rules remain distinguishable from evaluated domain rejections, and rule metadata is captured once per evaluation. Portable snapshots reject values that cannot be represented safely in their versioned JSON schema.

Development

The test suite includes vehicle-pricing and subscription-billing rulebooks, boundary and timezone cases, conflict and missing-match inspection, container injection, nullable outcomes, Carbon test time, exception propagation, architecture constraints, and PHPStan outcome inference.

License

Laravel Rulebook is open-source software licensed under the MIT license.