goro

Goro

PHP engine implemented in pure Go. Feature-complete for PHP 8.5 language features.

Why?

PHP is a nice language but is having trouble keeping up with modern languages. This implementation makes a number of things possible:

• Usage of goroutines, go channels, etc from within PHP
• Better caching of compiled code by allowing sharing of compiled or live objects (classes, objects, etc) between running PHP scripts
• Use Go's memory management within PHP
• Ability to run functions or code sandboxed (including filesystem via fs.FS) to limit security risks
• Easily call the PHP engine from Go to execute pieces of PHP code (user provided or legacy)

Install

go install github.com/KarpelesLab/goro/sapi/php-cli@latest

Status

Goro passes ~11,864 of 12,121 tests (~97.9%) from the PHP 8.5.5 test suite (~170 failures, 87 skipped in CI). PHP memory_limit enforcement (128MB default). Includes PCRE2 via gopcre2, IANA timezones via gotz, and 10 extensions (session, xml, curl, gd, sockets, zlib, mysqli, sqlite3, bz2).

Remaining test failures by area

SAPIs

Extensions

Not yet implemented

Bytecode VM (experimental)

A stack-based bytecode VM runs in parallel to the AST tree-walking executor. It's opt-in and falls back to the AST per-function on any unsupported construct.

Enable it with the GORO_VM=1 environment variable:

GORO_VM=1 php-cli script.php

The VM emitter currently handles:

• Scalar literals (int, float, string, bool, null) — including the case-insensitive constants true/false/null.
• Variable read/write, with a per-frame slot cache so reads skip the FuncContext hashtable entirely. Functions with no extract/compact/$$x/global/static/$GLOBALS use further perform slot-only writes (skip the hashtable mirror) for a sizeable perf win on write-heavy loops.
• Arithmetic / bitwise / shift / comparison / concat / unary (-, ~, !); plain and compound assignment (=, +=, …); pre/post ++/--.
• Short-circuit && / || and ?? (null coalesce, simple-variable LHS only).
• if / elseif / else, while, for, foreach (value form, array + object iteration), break / continue (single level), return, throw, try / catch (multi-type union, multi-clause, destructor-during-catch-bind chained correctly), try/finally (delegated to the AST runner so finally runs on every exit path).
• String interpolation ("hello $name", "v={$x}") lowered to a chain of OP_CONCAT.
• Array literals ([…], including keyed k => v); $a[$k] read; $a[$k] = v and $a[] = v writes (with auto-vivification from null/false and string-offset semantics).
• Object instantiation (new Cls(args…)), property read ($obj->prop), method call ($obj->m(args…)) with full PHP visibility checks (private/protected) and __call fallback. $this outside object context throws the correct Error. Class const / static prop / Foo::class (Foo::CONST, self::method, Foo::$bar, Foo::class) are AST-delegated for full CompileDelayed / visibility / LSB semantics.
• Builtin and user-defined function calls (positional args). Calls to by-ref builtins (end, sort, array_walk, array_push, …) fall back to AST so the by-ref binding works.
• Inline closures (function() { … }, fn() => …) with use captures, $this binding, and arrow auto-capture. Indirect calls ($f(), [$obj, 'method']()) resolve the callable at runtime via compiler.ResolveCallable and forward the implicit $this.

Out of scope (falls back to AST per-function via ErrUnsupported):

• By-ref returns and by-ref parameters on user-defined functions (the VM passes pre-evaluated ZVals; the AST passes Runnables and binds Writables).
• Generators (yield).
• $obj->prop = v and other property writes (deferred until a public WriteValue helper exists).
• Nullsafe chains ($obj?->...).
• Spread (...$arr) and named arguments.
• Dynamic names ($$x, $obj->{$x}, new $cls()).
• Multi-level break N / continue N.
• Type-hinted return values (the AST coerces; the VM doesn't yet).
• User-defined constants (PHP_INT_MAX, MYAPP_FOO, …).
• List destructure, anonymous classes, extract/compact/$$x and similar locals-introspecting builtins (those force slot-only off; currently we just compile-time bail when the body uses them).

Functions matching any of the above run as AST as before — the engine silently picks the right backend per-function, with no behaviour change.

Bench wins (vs. AST baseline, per-iter):

Larger gains require either an unboxed value type, slot-only writes (skipping the hashtable mirror) for slot-safe functions, or register-based opcodes. The 64-bit instruction format already has room for the last one.

Architecture

Process

A process object is typically created once per runtime environment. It caches compiled code and holds global stream wrapper resources, persistent connections, and runtime cache.

Global

When a request is received or script execution is requested, a new Global context is created. It contains runtime state: global variables, declared functions, classes, constants, output buffers, and memory limits.

Context

Context is a local scope (e.g., within a running function). Global has a root context, and each function call creates a new context to separate variable scope.

Contributing

See development.md for details on writing extensions.

Writing an extension: create a directory in ext/, write functions with magic comment prefixes, run make buildext to generate bindings, and add the extension import to each SAPI's main.go.