Axiom Laravel Package

Getting Started

Axiom is a small expression/overload-resolution package: you register rules or overloads and evaluate inbound values against them. v0.6.10 is the first release worth pinning deliberately, because it ships a resolution-order fix that changes results for a real class of inputs.

Minimal steps:

composer require gosuperscript/axiom
php artisan vendor:publish --tag=axiom-config   # if the config tag exists in your version
php artisan test

Look first at:

1. config/axiom.php — overload/resolver registration and any priority ordering.
2. Your AppServiceProvider::boot() (or a dedicated AxiomServiceProvider) — where overloads are declared.
3. The package's own tests for presence handling — that is exactly what moved in this release and is the fastest way to understand intended semantics.

First use case: validating a request payload where a field may be absent rather than merely empty. Axiom's job in that scenario is to decide whether a value is present at all before it tries to match it against an equality-based overload. Before v0.6.10, ordering was ambiguous; now presence is resolved first, so 0, '', false, and "key missing" stop collapsing into the same branch.

Implementation Patterns

Register overloads in a dedicated provider, not inline. Keep overload definitions in one class so the resolution order is auditable in a diff:

// app/Providers/AxiomServiceProvider.php
public function boot(): void
{
    Axiom::overload('status', fn ($value) => match (true) {
        Axiom::presence($value)->isAbsent() => 'missing',
        $value === 0                         => 'zero',
        $value === ''                        => 'blank',
        default                              => 'set',
    });
}

Rely on presence-first ordering explicitly. Since v0.6.10 resolves presence before equality overloads, you can now write presence checks as the first branch of a match and trust that they win. Do not rely on registration order to achieve this — express it in the match itself so the intent survives future releases.

Use it behind a custom validation rule. Wrap Axiom in a Rule object so it composes with FormRequest and Validator::extend idioms your team already knows. This also gives you a single place to log which overload matched.

Bind a configured instance in the container rather than using the facade in jobs and console commands. Overloads registered in a provider are fine for HTTP, but long-running workers need the registry rebuilt per job or resolved once at boot — pick one and document it.

Test the boundary values, not the happy path. A dataset of null, missing key, 0, '0', '', false, [] against each overload is the only meaningful regression suite here.

Gotchas and Tips

This is a patch release with a behavioral change. "Resolve presence before equality overloads" means inputs that previously matched an equality overload may now short-circuit into a presence branch. If you had a loose equality overload catching null/absent values, re-run your suite: any rule that treated 0 == null or '' == false as equivalent will now diverge. Nothing to change in your code unless a test fails — but a failing test here is the intended signal.

Distinguish absence from emptiness early. If the package distinguishes "key missing" from null, decide in your application which one you actually mean and normalise at the request boundary. Ambiguity there is what produced the bug this release fixed.

Debug by dumping the candidate chain. When an overload matches unexpectedly, log every candidate and its priority before the match runs. Chasing resolution order through match(true) expressions without that log is slow.

Extension points are the resolver/ordering hooks, not subclassing the evaluator. If you need custom precedence beyond presence-before-equality, register a resolver with an explicit priority rather than patching the evaluator.

Config caching: if overload priorities live in config, php artisan config:cache will freeze them at deploy time. Re-cache on every deploy and never override priorities at runtime in a cached environment.

Pin the version. "gosuperscript/axiom": "0.6.10" — the 0.x line is still making semantic decisions like this one, and exact pinning keeps the resolution order stable across deploys.