github lisachenko/z-engine 8.6.0
Release 8.6.0

one hour ago

PHP 8.6 is here, and Z-Engine supports it from day one.

Z-Engine 8.6.0 is the first stable release of the 8.6 line. You get the full Z-Engine toolkit on the newest PHP: operator overloading, custom object handlers, runtime engine modules, AST rewriting, opcode handlers and live code redefinition. Every engine definition in this release was checked against the PHP 8.6.0 release build itself, not a beta.

This release also brings a big upgrade to hot-swapping, first-class opcache support, and a long list of hardening fixes made for long-running processes.

composer require lisachenko/z-engine:~8.6.0

🚀 Highlights

Built for PHP 8.6, from the inside out

Z-Engine reads the engine's own C structures byte for byte, so a new PHP minor means a new engine. We followed PHP 8.6 through every beta and RC so that 8.6.0 lands complete:

  • Fresh engine definitions for linux-x64 and macOS (Intel and Apple Silicon), in both NTS and ZTS builds. The Linux definitions regenerate byte for byte from the PHP 8.6.0 GA build.
  • The new language is covered. The AST and opcode tables know PHP 8.6's additions, including partial-application placeholders (AST_PLACEHOLDER_ARG, SEND_PLACEHOLDER, CALLABLE_CONVERT_PARTIAL) and TYPE_ASSERT.
  • The engine changes are absorbed. Closures now bind $this through a plain object pointer, class and function types are real C enums, internal functions share user functions' argument layout, and hash-table insertion is stricter. Your code doesn't have to care about any of it.
  • Opcode handlers work on every VM. The PHP 8.6 tail-call VM bug that broke custom opcode handlers (#280) was traced to php-src and fixed upstream in php/php-src#24109. Custom handlers work on every dispatch mode again, and the new Core::getVirtualMachineKind() returns a typed VmKind enum so you can see which one you're on.

Hot-swap, levelled up

Redefining code at runtime is one of Z-Engine's signature tricks. In 8.6.0 it gets much more capable:

  • Keep the original. redefine() takes a preserveAs: name and keeps the previous body callable under it. Wrapping a method takes one line:

    $method->redefine(fn() => 'wrapped:' . $this->handleOriginal(), preserveAs: 'handleOriginal');
  • Borrow a body. Pass another class's method to redefine() and the entry adopts it in place. The method keeps its name, scope, visibility and prototype, and takes the donor's compiled body, signature and attributes. ReflectionClass::addMethod() accepts donors too, and applies the engine's real inheritance rules.

  • Patch code that is already loaded. The new CacheImageSync compares a patched opcache file-cache image against the running process and swaps every changed function and method body into code that is already loaded. There's no re-include, and existing function pointers stay valid.

  • Much faster swaps in large apps. A body swap now surveys the class table once per redefinition instead of once per question. Before, a single redefine() cost about 190 ms in a process holding 1,800 classes.

Opcache, fully on board

Z-Engine now runs comfortably next to opcache instead of working around it:

  • Hooked classes stay hooked. Z-Engine tells opcache not to cache a class that carries handlers, so the class stays process-local and its handlers keep firing. Unhooked classes are cached exactly as before.
  • A complete file-cache toolchain. The binary-cache relocator now covers trait aliases and precedences, union and intersection types, closures and arrow functions, iterator and ArrayAccess slots, property-hook bodies, and ZTS payloads. Relocation offsets are bounds-checked.
  • A graph-growing serializer. The new ScriptSerializer writes a fresh, valid cache image from a mutated script graph, using a port of the engine's own persist pass.
  • The optimizer is accounted for. Opcache's optimizer can remove or renumber local variables. ExecutionData::hasLocalVariable() and getLocalVariableNames() let you check what a live frame actually holds before you read from it. Static variables of opcache-shared functions are read correctly, and shared-memory method bodies can now be patched without the old 2 GB literal-reach limit.
  • Preloading on web SAPIs. ffi.enable=preload gets clear configuration guidance, and ffi.preload now works next to opcache.preload.

🛡️ Stability and memory safety

Z-Engine works directly on engine memory, so correctness is the main feature. This release closes a series of lifetime bugs found by debug-build and destructor-path testing:

  • Hot-swap: a use-after-free in the engine's class-name cache after HotSwap::apply()/discard() is fixed. ReflectionClass::bindClassNameCache() now repoints the cache at the live class.
  • Copies of a swapped entry stay valid. That covers fake closures, first-class callables, interface-induced engine clones and subclass method tables. Run-time caches and static variables are released exactly once, by the right owner.
  • Correct checks. Immutability is judged by the owning class, and self/parent in donor signatures resolve against the class that declares them.
  • Debugger-safe. __debugInfo() on function and method wrappers no longer throws. Before, it could crash a process stopped at an Xdebug or PhpStorm breakpoint inside redefine().
  • Reliable boot. The engine-constants artifact loads eagerly in Core::init(), and the live-closure walk skips closures over internal functions.

🧰 Developer experience

  • PHPStan understands PHP 8.6. The codebase is analysed at level max with phpVersion: 80600.
  • A clearly marked low-level API. Every public method that returns raw FFI\CData or a struct view is now tagged @internal, and a bundled PHPStan rule enforces it. The supported API and the escape hatches are now easy to tell apart (#194).
  • Generated definitions in CI. Linux engine definitions are now generated natively on the CI runner and diffed against the committed ones, the same way macOS and Windows are already handled. Definitions can't drift from the PHP build they describe.

📦 Platform support

PHP Platforms Z-Engine line
8.6 linux-x64 (nts, zts), darwin-x64 (nts, zts), darwin-arm64 (nts, zts) 8.6.x (this release)
8.5 linux-x64, darwin-x64, darwin-arm64, windows-x64 (nts, zts) 8.5.x
8.4 linux-x64, darwin-x64, darwin-arm64, windows-x64 (nts, zts) 8.4.x

Windows on PHP 8.6: windows-x64 definitions are coming in a follow-up release. Until then, use the 8.4 or 8.5 line on Windows.

Requirements: PHP ~8.6.0 with ext-ffi, ffi.enable=1 (or preload), and opcache.jit=off.


⬆️ Upgrading

Z-Engine follows PHP minors: 8.6.x is for PHP 8.6 only. Each minor rides its own line, and Core::init() refuses to boot on a mismatch rather than corrupting memory. The usual setup is to require one line per supported minor and let Composer pick the right one:

"lisachenko/z-engine": "~8.4.2 || ~8.5.0 || ~8.6.0"

If you were on 8.6.x-dev: switch your constraint to ~8.6.0. You can then drop any root-level minimum-stability/@dev workarounds you added for the preview.

Some changes come from PHP 8.6 itself and are visible through Z-Engine's API:

  • NodeKind (AST):
    • AST_METHOD_REFERENCE is now AST_TRAIT_METHOD_REFERENCE.
    • AST_PARENT_PROPERTY_HOOK_CALL was removed by PHP 8.6.
    • AST_PLACEHOLDER_ARG is new.
    • AST_PIPE and AST_CONST_ENUM_INIT have new numeric values.
  • OpCode: adds TYPE_ASSERT, CALLABLE_CONVERT_PARTIAL and SEND_PLACEHOLDER.
  • Raw accessors: methods returning raw FFI\CData are now marked @internal. They still work, but PHPStan will flag uses outside Z-Engine. Prefer the typed wrappers.

🌍 The ecosystem moves with it

Packages built on Z-Engine are moving to PHP 8.6 with this release, each with its full test suite as a required check on 8.6:

With this tag they can move from the development branch to a stable ~8.6.0 constraint.


⚠️ Still experimental, still not for production. Z-Engine works on raw engine memory. That's the source of its power and of its sharp edges. Run it where a segfault is a bug report, not an outage.

Full changelog: 8.5.0...8.6.0

Don't miss a new z-engine release

NewReleases is sending notifications on new releases.