Download the PHP package manticorephp/compiler without Composer

Manticore

Self-hosted PHP-to-native AOT compiler. Compiles a large subset of PHP 8.5+ to standalone native binaries (arm64 / x86_64) through LLVM IR — no PHP runtime, no shared libraries beyond libc. The compiler is written in PHP and compiles itself to a byte-identical fixpoint.

The output has no interpreter to install, no php.ini, no extension list — you ship the binary. What you write is ordinary PHP: the Zend interpreter is the reference, and every plain-runnable test case is diffed against it. On top of that sits a superset php cannot run at all — structured concurrency, FFI, a module system, compile-time attributes.

Requirements

Emitted binaries need nothing but libc. The compiler needs a real toolchain on the host, because it ends in clang and cc:

The -dev / -devel half matters: the headers are what the build looks for, not just the runtime library.

Platforms: macOS (arm64 / x86_64) and Linux (glibc ≥ 2.33, arm64 / x86_64). Each builds the compiler and passes the full suite including the self-host fixpoint. Alpine (musl) builds; see docs/install.md for the current caveats.

Per-OS package lists, Docker images and troubleshooting: docs/install.md.

Install

There is no prebuilt binary to download — the compiler compiles itself. The installer checks the toolchain above, tells you what is missing, then installs under $MANTICORE_HOME (default ~/.manticore):

Re-running the installer upgrades in place: an existing manticore rebuilds the new version with itself (self-host, fast) — the Zend seed is only the cold first boot. Knobs: MANTICORE_HOME, MANTICORE_REF (branch/tag), MANTICORE_REPO, MANTICORE_SRC (build a local checkout instead of cloning).

Via Composer, which here is a delivery + build trigger rather than a runtime:

The installed layout is self-contained and needs no environment variables — the binary finds its runtime relative to itself:

From a checkout

Working with it

Everything else is inspection — every stage of the pipeline is dumpable:

Flags: -o <out>, -O<0|1|2|3|s|z> (clang opt level, default -O2), --emit-library (a standalone .o with no @main), --memory=rc|arena|hybrid, and --prelude / --effects for the dump-* commands. compile analyzes by default and prints warnings without failing the build — --no-analyze turns it off, --analyze-strict makes error-severity findings fail the compile (rc=65). analyze adds --deep (also run the MIR type passes), --json, and --baseline / --generate-baseline to suppress known findings. --backend=<mir|ast> is still parsed but inert — MIR is the only backend. build also takes --libs-only (build the library targets and stop) and --keep-ir (leave the generated <output>.dbg.ll / .dbg.o next to the target instead of staging them in /tmp and deleting them — pair with -O0 to get a binary lldb can walk).

⚠ The dump-* commands do not link the stdlib, so a call into it resolves as unknown. When that matters, read the final binary.

The PHP you get

Classes / interfaces / traits / enums (enum methods, constants, interface-implementing enums), abstract + anonymous classes, late static binding (new static, static::method(), parent::/self:: forwarding), magic methods (__get/__set/__call/__invoke/__clone/__destruct), clone-with, 8.4 property hooks + asymmetric visibility, closures + first-class callable syntax (f(...)), by-ref / variadic params + argument unpacking, dynamic callables, the pipe operator |>, match, DNF types, ?? / ?->, global / static locals, heredoc / nowdoc, string interpolation, constants, generators (yield / yield from), exceptions with try/catch/finally and real stack traces, references to an array element / object property and out-parameter auto-vivification (preg_match($re, $s, $m)), reference returns, attributes, Reflection, Fibers, and file I/O over libc.

Generics are docblock-driven, so the source stays valid PHP: @template with bounds and defaults, @extends/@implements, generic traits (zero-cost), and reified @var Box<float> = new Box — a real specialized class, no boxing — plus implicit monomorphization of erased array / callable params (docs/generics.md).

Standard library: the array_* family in full, strings (incl. the whole preg_* family over host PCRE2), type/reflection, math, ctype_*, JSON, var_dump/print_r, SPL, date/time, sockets and streams, hashing and crypto. Each function is either a PHP-level stdlib function (src/Runtime/Stdlib/, compiled into lib/manticore_stdlib.o and auto-linked), an injected prelude helper, or an inlined codegen builtin. No imports, no registration — they are simply there.

Current gaps are tracked with repros in docs/ROADMAP.md; the headline ones are listed under Limitations.

Beyond PHP — the superset

Parity is the north star and tools/difftest.sh enforces it. The rest — the surface php cannot run, and difftest therefore cannot check — is catalogued in docs/superset.md: concurrency, compile-time attributes, FFI, the module system, the type system, the memory model.

The headline is structured concurrency — Go's model, PHP's spelling, written in PHP over two primitives of ours (native Fiber on fcontext, and Io\Poll over kqueue/epoll):

Ordinary fread/fwrite/stream_socket_accept/sleep suspend the fiber instead of the process — plain streams are the async API, TLS and DNS included. Every task is owned by a scope, cancellation is delivered at the suspend point, a deadlock is reported rather than exited, and Async\dump() names every live task and where it was spawned. An 8-worker prefork HTTP server does 150–160k rps (wrk, plaintext keep-alive). See docs/async.md.

Native libraries (zlib, libcurl, …) bind through FFI — #[Library, Symbol] attributes compile to direct C calls, and #[Library] is what puts the library on the link line; mechanism and C-type vocabulary in docs/ffi.md. The module system (docs/modules.md) is a cargo-style manticore.json with applications and libraries, .sig module interfaces so a dependent target resolves cross-unit calls without re-parsing sources, and a distributable compiler that ships bin/ + lib/ with no PHP sources at all.

Performance

Native AOT output vs the Zend interpreter, Apple M1 Pro, -O2, best of 5 (REPS=5; the script defaults to 3), every compiled program verified byte-equal to php first. Loops are data-dependent and $argc-seeded so LLVM cannot fold them away. Representative slice — reproduce with REPS=5 bash bench/run.sh (cases in bench/cases/):

Compute-bound work wins big (no per-op dispatch). The library-bound tail is the tightest race — those helpers compete with PHP's hand-tuned C — and native still wins every one. Also: cold start 2.6 ms vs 62 ms (~24×), a trivial program links to a ~50 KB fully-static binary, and fib.php compiles to native in ~0.1 s.

How it is built

Memory (docs/memory.md): reference counting on strings, objects, vecs and assoc arrays with copy-on-write, so frees are deterministic and there are no GC pauses; a synchronous Bacon–Rajan cycle collector that is opt-in and zero-overhead until gc_collect_cycles() is reached; and three allocation modes (--memory / MANTICORE_MEMORY) — hybrid (default, escape analysis routes each allocation between arena and heap-rc), rc, arena.

Source layout — pure PHP, one class per file, path mirrors FQN:

Gates

selfhost_fixpoint.sh asserts gen2 IR == gen3 IR, runs the suite through the self-built compiler, and rebuilds repeatedly to catch build-to-build layout roulette. The Linux gate is not optional for anything touching src/Runtime/, syscalls or errno.

Limitations

• Integer overflow wraps (two's-complement) instead of promoting to float — PHP_INT_MAX + 1 gives PHP_INT_MIN.
• extract() is not implemented (dynamic symbol-table writes the typed frame does not model). compact() works.
• goto into a loop body is unsupported (plain forward/backward goto works).
• Cycle collector is manual-trigger only and does not scan static/global roots.
• traits and generic classes do not cross a compiled-library boundary. Classes, interfaces, enums and constants do (.sig schema 2); a trait and a @template class both need their method bodies on the far side.
• json_encode of an object answers {} — the encoder lives in manticore_stdlib.o, a separate module with no user classes in its table.
• Regular-file I/O blocks the async loop by design; see docs/async.md for the measurements and Async\readFile().

The full, current gap matrix with repros lives in docs/ROADMAP.md.

License

Licensed under the MIT License.