Laravel Rulebook

How do you install Laravel Rulebook?

Install it with Composer. Laravel discovers the provider automatically. There is no configuration to publish, migration to run, facade, or global registry.

composer require mathiasonea/laravel-rulebook

A resolved decision gives you the outcome, winning rule, reason, and decision time:

$decision = $vehiclePricingRulebook->resolveAt(
    subject: $vehicle,
    at: $invoice->issued_at,
    context: $pricingContext,
);

$price = $decision->outcome();
$rule = $decision->winningRule();
$reason = $decision->winningResult()->reason();

How do you define a typed rulebook?

Extend Rulebook and return your rule classes. The PHPStan annotation connects the subject, context, and outcome types. Array order does not decide the winner.

/** @extends Rulebook<Vehicle, VehiclePricingContext, Money> */
final class VehiclePricingRulebook extends Rulebook
{
    protected function rules(): array
    {
        return [
            DefaultVehiclePrice::class,
            AustrianVehiclePrice::class,
            AustrianElectricVehiclePrice2025::class,
            AustrianElectricVehiclePrice2026::class,
            AustrianElectricVehiclePrice2027::class,
        ];
    }
}

How do you keep old rule versions?

Give each policy version its own validity period and behavior. Checks that do not change can stay in an abstract rule. Each yearly rule only needs to provide the values or formula for that year.

final class AustrianElectricVehiclePrice2026 extends AustrianElectricVehiclePrice
{
    public function key(): string
    {
        return 'austria.ev-price.2026';
    }

    public function validity(): ValidityPeriod
    {
        return ValidityPeriod::between(
            from: new DateTimeImmutable('2026-01-01T00:00:00+01:00'),
            until: new DateTimeImmutable('2027-01-01T00:00:00+01:00'),
        );
    }

    protected function policyYear(): int { return 2026; }
    protected function basePriceInCents(): int { return 35_000_00; }
    protected function incentiveInCents(): int { return 2_800_00; }
    protected function batteryFeePerKwhInCents(): int { return 4_00; }
}

The class name is the default rule key. Use a stable domain key when a decision or snapshot will be stored outside the current request. A blank key throws InvalidRuleKey.

What belongs inside a rule?

Rulebook evaluates every in-window rule, including lower-priority fallbacks. I therefore treat evaluate() as a deterministic, side-effect-free operation.

• Use $input->at instead of reading the current clock inside a rule.
• Do not write data, send messages, or trigger other side effects from evaluate().
• Keep key(), priority(), and validity() stable while the evaluation runs.
• Write reasons that are safe and useful in logs or support screens.
• Let operational exceptions bubble instead of turning them into a domain rejection.

How does Rulebook select one winning rule?

Rulebook skips rules outside the requested date, then asks the remaining rules whether they apply to the subject and context. The applicable rule with the highest priority wins. Lower-priority matches stay visible as fallbacks.

$decision = $rulebook->resolveAt(
    subject: $vehicle,
    at: new DateTimeImmutable('2026-06-15T10:00:00+02:00'),
    context: $pricingContext,
);

$decision->outcome();
$decision->winningRule();
$decision->winningRuleKey();
$decision->winningResult()->reason();
$decision->evaluationFor('austria.ev-price.2026');
$decision->shadowedEvaluations();

If two rules share the highest priority, Rulebook throws AmbiguousRuleMatch. Registration order never breaks the tie. A missing match throws NoMatchingRule, duplicate rule keys throw DuplicateRuleKey, and blank keys throw InvalidRuleKey.

How do you inspect a decision without requiring a winner?

Use evaluateNow() or evaluateAt() when you still want the results if no rule wins or two rules tie. The evaluation includes applicable, inapplicable, lower-priority, skipped, and conflicting rules with their reasons.

$evaluation = $rulebook->evaluateNow($subject, $context);

$evaluation->evaluations();
$evaluation->applicableEvaluations();
$evaluation->inapplicableEvaluations();
$evaluation->shadowedEvaluations();
$evaluation->conflictingEvaluations();
$evaluation->evaluationFor('austria.ev-price.2026');
$evaluation->hasWinner();
$evaluation->hasConflict();

How do statuses and reason codes work?

Each rule evaluation has one status: RuleEvaluationStatus::Applicable, RuleEvaluationStatus::DoesNotApply, or RuleEvaluationStatus::OutsideValidity. The last one means the rule was skipped and its application code did not run.

A human-readable reason is always present. Add an optional reason code when the application needs stable filtering, metrics, or localization.

return RuleResult::doesNotApply(
    reason: 'The vehicle is not electric.',
    reasonCode: 'vehicle_not_electric',
);

How do you keep the exact decision?

resolveAt() evaluates the currently deployed code and data at an explicit date. When the exact result must survive later changes, create a portable snapshot when the decision is made.

$snapshot = $decision->snapshot(
    normalizeOutcome: static fn (Money $money): array => [
        'currency' => $money->currency,
        'amount_in_cents' => $money->cents,
    ],
);

$record = $snapshot->toArray();
$json = json_encode($snapshot, JSON_THROW_ON_ERROR);

Can you run a complete Laravel Rulebook example?

Yes. The Austrian EV pricing example is a console-only Laravel 12 application that installs Rulebook from Packagist. It compares three fictional yearly policies for the same 75 kWh vehicle.

composer install

php artisan vehicle:price 2025-06-15T10:00:00+02:00
php artisan vehicle:price 2026-06-15T10:00:00+02:00
php artisan vehicle:price 2027-06-15T10:00:00+02:00

The command also prints the winner, its reason, the fallbacks, and the rules skipped because they were not valid at that date.

How do validity periods behave?

Validity periods are half-open: the start is included and the end is excluded. A range can omit either end. Dates become immutable values, and comparisons use absolute points in time without changing timezones.

• ValidityPeriod::always()
• ValidityPeriod::from($startsAt)
• ValidityPeriod::until($endsAt)
• ValidityPeriod::between(from: $startsAt, until: $endsAt)

When should you use Laravel Rulebook?

Use it when exactly one policy should win, rules change over time, fallbacks matter, and you need to explain the result later.

• Date checks keep accumulating in an application service.
• An older policy must still be available when evaluating an explicit date.
• Several rules can apply and the winner or fallback must be explicit.
• A decision varies by subject, context, and point in time.
• Support needs to see why a result was chosen.

Rulebook is for decisions with one code-defined winning rule. It does not provide a DSL, database or visual rule editing, workflow orchestration, or a way to combine results from several rules.

How is Laravel Rulebook tested?

The package uses Pest, Orchestra Testbench, Larastan, PHPStan deprecation rules, architecture tests, and Laravel Pint. Tests cover resolution and conflicts, validity boundaries, stable and invalid keys, captured rule metadata, structured statuses, reason codes, snapshots, custom outcome normalization, unsupported values, and invalid UTF-8.

composer test

Where can you follow Laravel Rulebook releases?

New versions are published through Packagist. Follow the GitHub releases for version notes.

Frequently asked questions