Wam Prolog Laravel Package

Getting Started

trismegiste/wam-prolog is a pure-PHP Prolog engine built on the Warren Abstract Machine. It is not a bridge to SWI-Prolog — everything (parsing, compilation to WAM instructions, resolution) happens in PHP. That gives you a zero-dependency, in-process inference engine, at the cost of speed and Prolog completeness.

Minimum steps:

composer require trismegiste/wam-prolog

If Packagist resolution fails (the package is old), install from VCS and check the composer.json php constraint — you may need --ignore-platform-reqs or a fork bumping the requirement:

composer config repositories.wam vcs https://github.com/Trismegiste/Prolog
composer require trismegiste/wam-prolog:dev-master

Where to look first, in this order:

1. README.md — the usage snippet for PrologCompiler / KnowledgeBase / Solver.
2. tests/ — this is effectively the real documentation; there is no API docs site and almost no third-party usage to learn from.
3. src/ term classes (Num, Str, Var, Term) — you need these to read query results back into PHP.
4. WamInstruction / instruction set — only if you plan to extend built-ins.

First use case: a small rule base compiled once and queried repeatedly. Keep it tiny (dozens of clauses) — ancestor/genealogy, permission rules, classification rules. Anything larger should be benchmarked before you commit to it.

$kb = new KnowledgeBase();
$kb->addTheory(<<<PROLOG
parent(tom, bob).
parent(bob, ann).
ancestor(X, Y) :- parent(X, Y).
ancestor(X, Y) :- parent(X, Z), ancestor(Z, Y).
PROLOG);
// then compile + solve; see README for the exact compiler/solver wiring

Treat the code above as the shape, not the literal API — verify class names against tests/ before you build anything on top.

Implementation Patterns

Wrap it in a facade from day one. The public surface is a handful of classes with mutable state. Put a single PrologEngine service in front of it exposing assert(string $theory) and query(string $goal): array. Because the package has 0 dependents and 32 stars, its API is whatever the tests say it is; your facade is the only place you'll need to change if it shifts.

Separate facts from rules. Rules belong in version-controlled .pl-style files under resources/prolog/. Facts belong in your database. At boot (or in a cached step), serialize DB rows into Prolog fact strings and prepend them to the rule file. This keeps the Prolog side readable and the data side testable.

Compile once, query many. Compilation to WAM instructions is the expensive part. Build the KnowledgeBase, compile it, and reuse the compiled structure for every query in the request — or better, cache it (file/Redis) keyed by a hash of the theory text. Recompiling per query is the most common accidental performance bug with this package.

Unwrap results into PHP arrays immediately. A solution is a set of Var bindings to terms. Don't leak Term objects into your domain layer; convert to scalars/arrays inside the facade, with an explicit mapping for compound terms.

Add native predicates sparingly. The engine exposes extension points for built-ins (PHP callbacks). Use them for I/O boundaries (looking up a value, logging, calling a service) — not for algorithmic work that belongs in PHP.

Test with micro-theories. One or two facts plus one rule per test. You get fast, deterministic tests and it documents your rule semantics. Assert on the full ordered result set, because backtracking order is observable and you want to notice when it changes.

Gotchas and Tips

It is unmaintained-by-community software. 32 stars, no dependents, no Stack Overflow corpus. Expect PHP 5-era idioms — possible each(), non-PSR-4 autoloading, loose namespacing, and E_DEPRECATED noise on PHP 8. Run a smoke test on your target PHP version before designing around it, and pin the version in composer.lock.

Performance is WAM-in-PHP, not SWI-Prolog. Expect milliseconds per simple query on a small KB, and quadratic pain on deep recursion. Set a hard cap on recursion depth / solution count, and benchmark with your real KB size early. If queries must be sub-millisecond or the KB exceeds a few thousand clauses, this is the wrong tool.

No tabling / no CLP(FD) / limited ISO coverage. Left-recursive rules will loop. Arithmetic is basic. Don't design rules that assume modern Prolog niceties; verify each built-in you rely on exists by reading the instruction set source.

String escaping and atom quoting. Atoms you generate from user or DB data must be quoted/escaped, or you get parse errors that surface as opaque compiler exceptions. Write one atom(string $s) helper and use it everywhere.

Variable naming. Variables are single-assignment within a clause but names are shared across the compiled theory in some implementations. Prefix generated variables (_G123) to avoid collisions with hand-written rule variables.

Cut and clause ordering matter. ! prunes the choice point stack; combined with clause order it's your only control flow. If results "disappear," suspect an over-eager cut or a rule ordered before a more specific one.

Debugging recipe. (1) Reproduce with the minimal theory in a unit test. (2) Dump the compiled WAM instructions to see whether the compiler or the solver is at fault. (3) Comment out clauses until the query returns, then bisect. Wrap solver calls in try/catch for PrologException — failures are exceptions, not false, in places you won't expect.

Where to extend. Built-in predicates and the instruction set are the supported seam. Do not patch the solver's unification or backtracking internals — without a test suite you trust, you will not know what you broke.

Have an exit plan. Because of the adoption profile, isolate the engine behind the facade and keep the rules in plain Prolog text. If you later move to SWI-Prolog via proc_open, a WASM build, or a modern PHP rule engine, only the facade changes — your theory files port unchanged.