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

Goro compiles every script body and user function to a stack-based bytecode and runs it on its own VM. The AST tree-walker remains as infrastructure for nodes the emitter doesn't lower piecewise (match, switch, anonymous class, dynamic-name access, etc.), but is no longer reachable as a standalone runtime.

The VM emitter handles natively:

• Scalar literals; true/false/null (case-insensitive); user constants (PHP_INT_MAX, MYAPP_FOO, …) via AST resolution.
• Variable read/write with a per-frame slot cache. Bodies with no extract/compact/$$x/global/static/$GLOBALS/by-ref also skip the FuncContext hashtable mirror on writes.
• Arithmetic / bitwise / shift / comparison / concat / unary (-, ~, !); plain and compound assignment (=, +=, …); pre/post ++/-- (including on object props, array elements, static props — those AST-delegate).
• Short-circuit && / ||; null-coalesce ?? (any LHS shape); ternary ?: / short ternary.
• if/elseif/else, while, do/while, for, foreach (value, by-ref, and non-local-target forms), match, switch, multi-level break N / continue N, return (incl. typed-return coercion via AST delegation), throw, try/catch/finally.
• String interpolation, array literals (incl. spread ...$arr), array reads and writes (incl. nested chains, append, compound).
• Object instantiation (incl. anonymous classes, dynamic class name, named/spread args), property and method access (incl. nullsafe ?->, dynamic-name, named/spread args), class const / static prop / Foo::class, clone, instanceof.
• Inline closures with use captures, $this binding, arrow auto- capture, indirect calls ($f(), [$obj, 'method']()).
• isset/empty/unset, list($a,$b) = … / [$a,$b] = … destructuring, variable variables ($$x, ${$expr}).
• Generator iteration: function() { yield … } itself runs through the AST (cooperative coroutine), but foreach over a generator drives it through the VM's iterator dispatch.

Known limitations (about 20 phpt failures unique to the VM, all reference-semantics or error-handler edge cases):

• ArrayAccess overloaded containers ($obj[$k] where $obj implements ArrayAccess) with by-ref propagation.
• Deep ref-cycle reshape patterns (bug72543*).
• A few error-handler/backtrace tests that depend on specific call-frame metadata that the VM doesn't replicate exactly.
• One isset string-offset edge case (bug31098).

These need either a ref-aware call protocol (pass Writable args through the VM stack) or a runtime fall-back that re-evaluates args from AST nodes when the resolved callee declares by-ref. Both are non-trivial architectural changes outstanding for a future pass.

Benchmark numbers (per iter, on the same machine before / after flipping the VM gate on permanently):

Larger gains require either an unboxed value type or register-based opcodes. The 64-bit instruction format already has room for the latter.

Importing the VM

Any binary or test that uses core/compiler must blank-import core/vm/vmcompiler so the package's init() installs the TryBuildVMScript / TryBuildVMClosureBody hooks. compiler.Compile panics with a clear message if those hooks are missing. All built-in SAPIs and the in-tree test files already have the import.

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.