Roadmap

Direction for upcoming 0.x releases

The roadmap stays in the 0.x series while the compiler, runtime, and product shape are still moving. Current work is focused on PHP parity, backend foundations, and concrete product tracks without a major-version release gate.

Current direction:

Finish the well-bounded PHP-visible compatibility gaps on the EIR backend.
Keep completed historical items in their original version sections.
Move optimizer work behind EIR, benchmark evidence, and real-world validation.
Treat shared libraries, the PHP extension bridge, and WebAssembly as later 0.x product tracks.
Leave the major-version discussion for the final future-perspective section.

v0.1.x — Usable CLI compiler (done)

v0.2.x — Arrays and null (done)

Indexed arrays: $arr = [1, 2, 3];
Array access, assignment, push: $arr[0], $arr[0] = 42, $arr[] = "new"
count(), array_push(), array_pop()
foreach ($arr as $value) { } loop
in_array(), array_keys(), array_values(), sort(), rsort(), isset()
Heap allocator (1MB bump allocator)
Proper null: echo null prints nothing, is_null(), null coercion in operations

v0.3.x — Bool, float, and type system (done)

Proper type system for PHP compatibility.

Bool type

true/false as distinct Bool type
echo false prints nothing, echo true prints 1 (like PHP)
Bool coercion: false → 0/"" in arithmetic/concat, true → 1/"1"
is_bool(), boolval()
=== and !== strict comparison (type-aware)

Float type

Float literals: 3.14, 1.0e-5, -0.5
Division returns float: 10 / 3 → 3.3333...
intdiv() for integer division
Mixed int/float arithmetic (auto-promotion to float)
Float comparison and formatting
floatval(), is_float(), is_int(), is_string(), is_numeric()
INF, NAN, is_nan(), is_finite(), is_infinite()

Type operations

Type casting: (int), (string), (float), (bool), (array)
gettype(), settype()
empty() — check if variable is empty/falsy
unset() — destroy variable

Math functions

abs(), min(), max(), floor(), ceil(), round()
sqrt(), pow()
** exponentiation operator
fmod(), fdiv()
rand(), mt_rand(), random_int()
number_format()
Constants: PHP_INT_MAX, PHP_INT_MIN, PHP_FLOAT_MAX, M_PI

v0.4.x — Strings (done)

v0.5.x — I/O and file system (done)

v0.6.x — Associative arrays and switch (done)

v0.7.x — Advanced language features

v0.8.x — Date/time, JSON, regex

v0.9.x — Memory management (done)

v0.10.x — Basic classes (done)

v0.11.x — Reference-counting garbage collector (done)

Reference counting infrastructure (header: [size:4][refcount:4], zero overhead)
Runtime: __rt_incref, __rt_decref_array, __rt_decref_hash, __rt_decref_object
unset() uses decref (frees when refcount drops to zero)
GC statistics (--gc-stats flag: allocations, frees printed to stderr)
Strings freed on variable reassignment (value-copied, always owned)

Known limitations

Ordinary local/global reassignment now releases previous arrays/objects safely, and indexed array writes / associative-array writes / object property writes / static slots now retain borrowed heap values consistently
Automatic epilogue cleanup has since been re-enabled for locals proven to own heap values; the remaining gaps are conservative control-flow merges and cyclic graphs
Assoc-derived and broader container-copy paths now retain borrowed heap values consistently; the main remaining memory-model work has moved to targeted cycle collection, richer debug instrumentation, and tighter ownership precision

v0.12.x — Math coverage (done)

Trigonometry

sin(), cos(), tan()
asin(), acos(), atan(), atan2()
deg2rad(), rad2deg()
sinh(), cosh(), tanh()

Logarithms and exponentials

log() — natural logarithm
log2(), log10()
exp() — e^x

Utility

hypot() — sqrt(x² + y²)
pi() — alias for M_PI

Constants

M_E, M_SQRT2, M_PI_2, M_PI_4, M_LOG2E, M_LOG10E
PHP_FLOAT_MIN, PHP_FLOAT_EPSILON

v0.13.x — Pointers

Opaque pointer type (ptr) for handles and void*
Typed pointer tags via ptr_cast<T>() for annotating raw addresses with a checked pointee type
Pointer builtins: ptr(), ptr_null(), ptr_is_null(), ptr_offset(), ptr_cast<T>(), ptr_get(), ptr_set()
Raw buffer pointer builtins: ptr_read8(), ptr_read32(), ptr_write8(), ptr_write32()
ptr_sizeof() — returns byte size of a type ("int" → 8, "float" → 8, class name → computed)
Pointer echo: echo $ptr prints hex address (0x...)
Pointer comparison: ===, !== between pointer values

v0.14.x — FFI (Foreign Function Interface)

v0.15.x — Memory model hardening

v0.16.x — Language and runtime expansion

v0.17.x — Language maturity and compiler ergonomics

v0.18.x — Multi-platform and optimizations

Linux x86_64 target
Linux ARM64 target
Split src/codegen/expr.rs into a slim dispatcher plus smaller focused helpers
Split src/codegen/stmt.rs into a slim dispatcher plus smaller focused helpers
Target support matrix: macos-aarch64, linux-aarch64, linux-x86_64

v0.19.x — Tooling, compiler throughput, and optimization

v0.20.x — PHP filesystem, expression, call, and callable parity closure

Close the small, well-scoped PHP filesystem/runtime compatibility gaps that are already adjacent to the current implementation, plus the language-level PHP behavior visible in everyday source code that does not require a new backend or product mode. This is also the series that delivered the Fibers MVP.

JSON parity polish (post v0.8.x base surface)

JSON_BIGINT_AS_STRING in json_decode(): integer-grammar tokens (no ., no e/E) whose magnitude exceeds PHP_INT_MAX (9223372036854775807) promote to a Mixed(string) preserving the original digits; in-range integers and float-grammar tokens are unaffected. Length-then-lex compare against the threshold strings 9223372036854775807 (positive) / -9223372036854775808 (negative) detects overflow without invoking __rt_atoi (which silently wraps via imul).
Lone UTF-16 surrogate detection in json_decode() / json_validate(): every \uXXXX escape in the high-surrogate range (0xD800..0xDBFF) must be immediately followed by a \uYYYY escape in the low-surrogate range (0xDC00..0xDFFF). Unpaired high surrogates and stand-alone low surrogates set JSON_ERROR_UTF16 (10) and raise JsonException under JSON_THROW_ON_ERROR, with the PHP-faithful message Single unpaired UTF-16 surrogate in unicode escape. The string parser accumulates each escape into a 16-bit codepoint and walks the surrogate-pair handshake before resuming content scanning.
PHP-strict depth semantics for json_decode() / json_validate(): PHP rejects when the active nesting depth equals the $depth argument (active >= limit), so a flat array fails at depth=1 and a one-level-nested container fails at depth=2. The shared __rt_json_depth_enter keeps the lenient active <= limit rule (used by json_encode() per PHP), and the decode/validate dispatchers pass $depth - 1 as the runtime limit so both surfaces match PHP exactly without forking the depth helper.
Exception::$code and Exception::getCode(): int. The constructor now accepts an optional $code = 0 second argument and stores it as a protected int property. JsonException thrown via JSON_THROW_ON_ERROR carries the originating JSON_ERROR_* code, so catch (JsonException $e) { $e->getCode(); } matches PHP exactly (4 = SYNTAX, 1 = DEPTH, 10 = UTF16, 7 = INF_OR_NAN, etc.). User-code new Exception("msg", $code) also surfaces the value through getCode().
is_callable($value): bool builtin. Compile-time decision when the value is a string literal (resolves against the catalog + user functions; case-insensitive for builtins) or a Callable-typed expression (closures, first-class callables). Non-literal strings, [$obj, "method"] arrays, and __invoke objects route to a future runtime helper.
Cache _json_active_flags in a callee-saved register (x19 ARM64 / r15 x86_64) inside __rt_json_encode_str: 8 reload sites collapse to a single-instruction tst/test against the cached register, eliminating one address-load + memory dereference per HEX_/UNESCAPED_/UTF-8 dispatch in the per-byte escape loop.

v0.21.x — PHP runtime and language parity

Close broad PHP-visible parity gaps across the value model, modern syntax, runtime helpers, and standard-library surfaces.

Standard PHP Library (SPL)

PHP-compatible Standard PHP Library coverage, rolled out in phases.

Serializable is intentionally not implemented — it has been deprecated since PHP 8.1.

v0.22.x — Core parity cleanup before EIR

Close the small dispatch, lvalue, and runtime correctness gaps that should not be carried through a backend migration.

Throwable-via-interface getMessage() dispatch fix (pre-existing): catching by Throwable and calling getMessage() on the typed binding returns garbage instead of the message string
$obj[$k] subscript syntax for ArrayAccess implementers (read, write, isset, unset paths), including Mixed-boxing for offsets and values
Raw pointer memory helpers for FFI/socket showcases: ptr_read16(), ptr_write16(), ptr_read_string(), ptr_write_string()
IntrinsicCall foundation for runtime-managed SPL/core objects when direct method interception is still the cleanest implementation path

v0.23.x — SPL containers and iterator runway

Continue SPL coverage on the 0.x path, but do not let broad library coverage block the EIR migration unless it exposes core dispatch, ownership, or lvalue gaps that must be fixed first.

Streams and sockets

End-to-end PHP streams/sockets/network subsystem, rolled out in phases on feat/streams-sockets. Each phase landed as an autonomous increment with its own tests; the descriptions below summarize the PHP-visible surface, not the internal commits.

Streams — remaining work (subsystem considered partially complete; merged as-is)

The streams/sockets subsystem covers the everyday PHP surface end-to-end (file I/O, all network transports incl. IPv6+DNS, TLS, the wrapper/filter/context families, and userspace stream_wrapper_register/stream_filter_register). The items below are intentionally deferred to a later milestone. They are either niche, genuinely large (multi-week), or blocked by an upstream-library limit — none are needed for typical stream usage.

Database access — PDO (SQLite, PostgreSQL, MySQL/MariaDB)

PDO database access, backed by the driver-agnostic crates/elephc-pdo bridge staticlib (C ABI, no system database dependency): statically-bundled SQLite plus the pure-Rust postgres and mysql clients. The PDO / PDOStatement / PDOException classes are implemented as an elephc-PHP prelude that calls the bridge through extern "elephc_pdo", so the feature compiles through the normal class/extern/exception pipeline with no bespoke intrinsics or hand-written assembly. The DSN prefix (sqlite: / pgsql: / mysql:) selects the driver at open(). The prelude is injected only when a program references PDO, so non-PDO binaries never link the bridge.

Type checker

Flow-sensitive type-guard narrowing — if / elseif / else chains guarded by is_int() / is_float() / is_string() / is_bool() (and the is_integer / is_long / is_double aliases) or $var instanceof Class narrow the guarded variable inside the matching branch, with an optional leading !, complement accumulation across the chain and else, and post-if narrowing when every branch diverges (return / throw / exit / die / never-returning calls); union members are filtered to the guarded type and Mixed is refined to it, while concrete non-union types are left unchanged (src/types/checker/stmt_check/narrowing.rs, tested in tests/codegen/types/narrowing.rs)

Runtime representation

Null-sentinel collision groundwork — one canonical NULL_SENTINEL constant (src/codegen/sentinels.rs) replacing seven file-local duplicates, i64::MAX - 1 disguises, and raw movz/movk chains; collision repros locked in tests/codegen/null_sentinel/ and the incompatibility documented in docs/php/types.md
Tagged null representation behind --null-repr=tagged / ELEPHC_NULL_REPR — inline two-word {payload, tag} TaggedScalar for null-capable scalars (miss-capable int array reads, empty array_pop/array_shift), tag-aware consumers (echo, var_dump, is_null, ??, ??=, isset, empty, gettype, casts, arithmetic narrowing, === via Mixed boxing), plain-int sentinel checks removed (full 64-bit int range round-trips, including 9223372036854775806), local inference and untyped-param widening aligned; covered on all three targets in tests/codegen/null_sentinel/tagged.rs
Flip the default null representation to Tagged (the collision bullet in docs/php/types.md now documents only the --null-repr=sentinel opt-out); the {payload, tag} shape is the convergence point for runtime int-overflow→float promotion

Date/time and calendar parity

Full OOP + procedural date/time surface (DateTime, DateTimeImmutable, DateTimeInterface, DateTimeZone, DateInterval, DatePeriod, and ~45 procedural functions/aliases), plus the complete ext/calendar extension, implemented as synthetic classes/methods over the date()/mktime()/gmmktime() runtime — no new codegen or assembly.

v0.24.x — EIR introduction and register allocation

Introduce a domain-specific intermediate representation (EIR) between the AST-level optimizer and the assembly emitter, then add a real register allocator.

EIR is a custom, PHP-shaped IR — not Cranelift or LLVM. It preserves the hand-written-and-commented assembly philosophy while removing the structural ceiling on optimization that the direct AST → ASM emitter imposed. See docs/internals/the-ir.md.

EIR design specification (docs/internals/the-ir.md) — types, instructions, terminators, effects, ownership, textual format
src/ir/ module — types, instructions, builder, validator, printer
AST → EIR lowering pass — every ExprKind/StmtKind variant
--emit-ir CLI flag for diagnostics and snapshot testing
EIR → ASM backend producing semantically equivalent output to the legacy backend (no optimizations yet)
Default backend switch from AST to EIR, with --ast-backend retained as an explicit fallback
CI default-EIR gate, frozen fallback smoke coverage, and IR-only benchmark job for parity and regression tracking
Linear-scan register allocator (Poletto-Sarkar) with liveness analysis, live intervals, allocation table, separate int / float pools, and callee-saved preservation across calls
Register-pressure mitigations: caller-saved reuse for non-call-crossing intervals; better spill heuristic. The linear-scan allocator now classifies each live interval as call-free (never crosses a clobber point — an instruction/terminator whose lowering emits a call or touches a caller-saved register, per the safe-by-default allowlist in src/ir_passes/clobber.rs) and assigns call-free intervals from caller-saved pools that need no prologue save/restore (x12–x15/d16–d23 on aarch64, rsi/rdi/r8/r9/xmm2–xmm7 on x86_64), falling back to callee-saved (x21–x28/d8–d14/rbx) for cross-call values. This notably unlocks register allocation for x86_64 floats (no callee-saved XMM) and integers (callee pool is only rbx). The spill heuristic is now use-weighted: under pressure the rarely-used, furthest-reaching interval is evicted first, keeping hot values in registers

Expected outcome: EIR is the default and only active implementation backend in v0.24.x. The legacy AST backend is frozen for diagnostics and removal work only, and ≥15% performance improvement on compute benchmarks after Phase 06 by end of v0.24.x.

v0.25.x — EIR optimization passes and Image support

EIR optimization passes

Build the IR-level passes that the AST optimizer could not reach now that the EIR backend is the user-facing default.

Expected outcome: EIR remains the only active backend implementation target, additional 10–20% performance gain on loop-heavy and call-heavy benchmarks, and cumulative ≥30% improvement vs end-of-v0.23 baseline.

Image support (GD, Exif/IPTC, Imagick, Gmagick, Cairo)

Complete PHP image surface on a pure-Rust bridge (crates/elephc-image, image/imageproc/ab_glyph/tiny-skia/kamadak-exif). Delivered through a PHP prelude (src/image_prelude.rs) + extern calls, like PDO/Phar, so binaries stay standalone (no system GD/libpng/libjpeg/ImageMagick). Imagick/Gmagick/Cairo are semantic reimplementations of their PHP APIs, not byte-identical to the original C/C++ libraries; operations with no pure-Rust path are documented, tested, diagnostic-emitting gaps.

Array builtin parity (key/list helpers, associative set-ops, recursive merge/walk)

Well-bounded PHP-visible array builtins implemented on the EIR backend. All target-aware (ARM64 + x86_64), with codegen and error tests; the shared __rt_* runtime helpers are reused and driven through EIR lowering.

v0.26.x — Performance closure, legacy cleanup, and 0.x stabilization

Optimization work should now be driven by benchmarks, generated assembly size, and 0.x validation rather than by speculative pass work.

Later 0.x product tracks

These are valuable product directions that build on the stabilized 0.x compiler and runtime foundation.

Web server (`--web`) — product track

elephc --web app.php compiles a standard PHP file into a standalone prefork HTTP server binary. The produced binary uses SO_REUSEPORT prefork workers; each request re-runs the top-level PHP body from a fresh state (globals, function statics, and static class properties all reset between requests). Run it with --listen host:port (required) and optionally --workers N (default: CPU count).

Phase 1 — core serve loop: elephc --web compile flag; --listen/--workers runtime args; _elephc_web_handler entry restructure for per-request invocation; __rt_stdout_write capture to the response body buffer; __rt_web_reset per-request state reset (function statics, static properties, concat buffer); elephc-web bridge staticlib with prefork/SO_REUSEPORT supervisor and per-worker hyper HTTP server. Every Phase 1 response is 200 OK with the echoed body.
Phase 2 — request input superglobals: $_SERVER (method/URI/query + HTTP_* headers + CONTENT_TYPE/CONTENT_LENGTH), $_GET (query string), $_POST (urlencoded body), and php://input (raw body), built per request by a --web web prelude and readable inside any function scope (true superglobals via _eir_global_* storage); output-capture completeness so echoed Mixed/array/ resource values reach the response body; superglobals released per request. Not included: $_REQUEST, multipart/form-data.
Phase 3 — response control: http_response_code() (set/read status, returns previous on set) and header(), fully PHP-compatible — replace-vs-append, HTTP//Status: status lines, Location:→302, and the third $response_code argument, all handled in the elephc-web bridge. Web-gated __rt_http_response_code / __rt_header forward to the bridge under --web and are no-ops otherwise. Not included: Content-Type is not set automatically (the program controls it).
Phase 4 — hardening: --max-body-size request body cap (413 on overflow), graceful SIGINT/SIGTERM shutdown (forward to workers, reap, exit 0), worker respawn on unexpected death, and a 30s header-read timeout bounding slow/idle keep-alive connections. Out of v1 scope: cookies, sessions, TLS, HTTP/2–3, multipart.
Phase 4.1 — compile-time handler isolation: plain --web preserves the original in-process worker path and performance; --web-isolation=pool selects persistent supervised handler children; request selects a tracked, disposable child per request. Isolated modes add configurable handler concurrency, body/response deadlines, streaming output, exact dispatch-ID cancellation, PID reaping/replacement, pool-child quotas, and descendant-safe shutdown without adding request-time branching or IPC to the default mode.
Phase 5 — session support: session_start(), $_SESSION superglobal, session_id(), session_name(), session_status(), session_save_path(), session_write_close() (auto-called at handler end via a finally block), session_regenerate_id(), session_unset(), session_destroy(), session_set_cookie_params() / session_get_cookie_params(), file-based storage (matching PHP's session.save_handler = files; an empty configured save path resolves to sys_get_temp_dir()), flock-based concurrency safety, PHP_SESSION_DISABLED / PHP_SESSION_NONE / PHP_SESSION_ACTIVE constants.
Phase 5.1 — session parity: predefined PHP_SESSION_* / SID constants (no runtime define()); custom save handlers via the object form session_set_save_handler(SessionHandlerInterface) plus SessionHandler, SessionIdInterface, SessionUpdateTimestampHandlerInterface; session.use_strict_mode, serialize_handler (php/php_serialize/ php_binary), lazy_write, probabilistic auto-GC (gc_probability/ gc_divisor/gc_maxlifetime), sid_length/sid_bits_per_character, complete session_cache_limiter() headers, session_abort()/session_reset()/ session_gc()/session_encode()/session_decode()/session_module_name()/ session_commit()/session_register_shutdown(). Also supports the legacy 6-callable session_set_save_handler($open, $close, $read, …) form (deprecated in 8.4) for function-name and closure callables, wired through a general enhancement that lets call_user_func/call_user_func_array dispatch a boxed Mixed callback by runtime tag; instance array callables [$obj, 'method'] in that form now dispatch through the same boxed-Mixed path (only static ['Class', 'method'] array callables still need the object form). Fixed a pre-existing CLI SIGSEGV (superglobal type seeding gated on --web) and two EIR ownership bugs on static property stores: a borrowed object is now acquired (so it dispatches after the borrow is released), and overwriting a Mixed/nullable-object static slot now releases the previous object instead of leaking it on every reassignment.
Phase 5.2 — session runtime configuration: ini_get() / ini_set() / ini_get_all() scoped to the session.* directive surface (PHP ini_get string convention — integers as decimals, booleans as '1'/''; unknown directives return false); session.auto_start seeded per worker from the ELEPHC_SESSION_AUTO_START environment variable (auto-starts the session in the request bootstrap, php.ini-PERDIR-style); session.referer_check enforcement (a cookie-supplied ID whose request Referer lacks the configured substring is invalidated, starting a fresh session). Adds the ini-settable config surface for session.use_only_cookies, session.use_trans_sid / trans_sid_*, and session.upload_progress.* (output URL-rewriting and live upload-progress runtime behavior tracked separately).
Phase 5.3 — php-src lifecycle and storage parity: binary-safe pointer/length payload ABI; files-handler [depth;[mode;]]path, nested GC, no-follow/ownership hardening, and complete writes; active callback status, abort/restart/read-and-close/regenerate sequencing; Cookie/GET/POST SID transport without redundant cookies; save_handler, cookie_partitioned, use_cookies, and lazy_write INI coverage; custom-handler lazy snapshots; and php_binary plus non-cookie upload-progress IDs.

v0.27.x — Shared and static libraries (C ABI)

v0.28.x — PHP extension bridge (experimental)

zval pack/unpack routines (convert elephc values ↔ PHP zval structs)
Link against PHP extension .so / .dylib shared libraries
Bridge for string, int, float, bool, array types
Proof of concept with one extension (e.g., mbstring or curl)
--ext flag to specify extension libraries at compile time
Documentation: how to bridge a PHP extension

v0.29.x — WebAssembly target

WASM codegen backend
.wat / .wasm emission
WASI support for I/O
NPM package generation

Deferred ideas

Features that are feasible but intentionally not on the active 0.x path. They are either product-specific, very high complexity, or better justified by concrete future use cases.

Feature	Complexity	Notes
Buffer ergonomics v2	Medium	Consider dynamic resize/push/pop, `foreach`, array conversion, and automatic cleanup for `buffer<T>` while keeping the hot-path POD contract explicit.
String-capable FFI callbacks	Medium	Allow C callback signatures that pass or return strings once ownership and temporary C-string lifetimes are modeled safely across callback boundaries.
Generator parity v2	Medium	MVP delivered in v0.21.x for ARM64 and Linux x86_64; `yield` inside `try`/`catch`/`finally` and exception propagation through `Generator::throw` landed with the v0.26.x closure work. Remaining parity work: dynamic `yield from` arrays beyond the compile-time literal form, broader dynamic `yield from` Iterator targets, and PHP-exact `Generator` interface inheritance with `Iterator`. See `docs/php/generators.md`.
Fiber parity v2	Medium	MVP delivered in v0.20.x for ARM64 and Linux x86_64. Remaining parity work: arithmetic auto-unboxing on `mixed` payloads received from `suspend()`, true variadic `start(...$args)` beyond seven args, dynamic callback targets, by-reference callback start parameters, configurable stack sizing, and PHP-exact `FiberError` hierarchy. See `docs/php/fibers.md`.
Conditional include class-like variants	High	Keep class/interface/trait/enum duplicate detection strict for now. Supporting branch-selected class-like declarations would require runtime class metadata/layout dispatch, while modern PHP can avoid the ambiguity with namespaces.

Future 1.0 perspective

1.0 is not an active planning gate for the current roadmap. Revisit it only after the 0.x compiler/runtime contracts have settled through real-world use.

Freeze the documented language/runtime contract for the supported target matrix
Decide which 0.x product tracks belong inside the first stable contract and which remain experimental
Run a dedicated stabilization pass across compiler, runtime, docs, examples, and packaging
Ship 1.0 from a proven 0.x baseline

Uh oh!