Download the PHP package lisachenko/native-php-matrix without Composer

⚠️ Experimental — educational first, production second. This library installs custom object handlers into a running Zend Engine. It is a demonstration of what userland PHP can reach, and it inherits every constraint of the machinery underneath it. Pin your PHP version, keep it out of production until there are stable tags on both this package and Z-Engine, and treat a crash as an engine-level bug report rather than a flaky test.

The first PHP "extension" written without C

For a long time operator overloading was the exclusive privilege of compiled extensions: write C, learn the zend_object_handlers struct, build a .so, ship a PECL release. This library is the first ever userland PHP extension that implements true operator overloading — and it does it entirely in PHP.

The trick is lisachenko/z-engine, which loads version-exact FFI definitions of the engine's C structures and lets PHP write into them. Matrix installs its own do_operation and compare handlers on its own class entry, so when the VM evaluates $a * $b and sees an object operand, it calls straight back into PHP code. The operators are not simulated, not parsed, not wrapped in a fluent API — the engine really dispatches them.

What you get

Every operation returns a new Matrix; the class is final and its state is readonly, so nothing is ever mutated in place. The constructor validates that you passed a rectangular list of rows holding only int/float cells and raises a catchable InvalidArgumentException when it does not.

Operator-level failures are a different story, and it is worth being blunt about it: a dimension mismatch (InvalidArgumentException) or an unimplemented operand combination such as $a - 2 (LogicException) is raised inside an FFI callback, and PHP does not allow an exception to cross that boundary. The engine prints the exception and then halts with Fatal error: Throwing from FFI callbacks is not allowed. You cannot try/catch it — check your dimensions before you multiply.

Generics are honest about arithmetic: Matrix<int> divided by 2 is a Matrix<int|float>, because PHP's / widens. Nothing pretends to preserve T where the maths does not.

How it works

Three moving parts, in order:

1. bootstrap.php is registered in Composer's files autoload, so it runs the moment you require vendor/autoload.php. It calls ZEngine\Core::init(), which validates that the FFI struct definitions match the exact PHP build you are running.
2. It then calls installExtensionHandlers() on ZEngine\Reflection\ReflectionClass for Matrix, wiring the class's create_object, do_operation and compare slots to the engine trampolines. Order matters — create_object allocates the memory the other handlers live in.
3. Matrix::__doOperation() and Matrix::__compare() are static hooks. The engine hands them a DoOperationHook / CompareValuesHook describing the opcode and both operands; they dispatch to ordinary, boring, pure-PHP methods (sum(), subtract(), multiply(), multiplyByScalar(), divideByScalar(), powByScalar(), equals()).

The maths is plain PHP. The magic is only in getting the engine to call it.

Requirements

• PHP ^8.4 — 8.4 and 8.5 are supported in parallel. Z-Engine reads engine structures by byte offset and those offsets change on every PHP minor release, so each minor rides its own Z-Engine line; Core::init() refuses to boot on a mismatch rather than corrupting memory.
• ext-ffi enabled, with ffi.enable=1 for CLI usage.
• x64, non-thread-safe (NTS) build — the same platform limitations as Z-Engine.
• The matching Z-Engine minor release line. Composer resolves it for you from the ~8.4.2 || ~8.5.0 constraint; mixing a Z-Engine built for another minor is not a configuration choice, it is undefined behaviour.

Installation

This package requires Z-Engine as ~8.4.2 || ~8.5.0 — z-engine minors track PHP minors and are not interchangeable, so Composer resolves the release line matching your PHP automatically (8.4.x on PHP 8.4, 8.5.x on PHP 8.5). Both are stable tags, so no minimum-stability tweak is needed for them.

native-php-matrix itself is not tagged yet, which is why the command above asks for dev-master; that one dev constraint is explicit, so Composer accepts it without a root stability change. Once a native-php-matrix release is tagged, this collapses to a plain composer require lisachenko/native-php-matrix.

No initialization call is needed: bootstrap.php ships in the package's files autoload and sets everything up behind require vendor/autoload.php.

Usage

The classic

Operator precedence is the engine's own, so * binds tighter than + exactly as you would expect from numbers.

Matrix by matrix

Powers and division

Comparison

Equality is element-wise and strict. Ordering operators (<, >) are deliberately not meaningful for matrices — the compare hook reports "unordered" rather than inventing a total order.

Casting

Casts are dispatched by the engine too — the cast_object and get_properties_for handlers:

Numeric casts keep the engine's default behaviour ((int) $m gives 1), and everything that is not a cast — var_dump(), serialize(), var_export(), json_encode(), get_object_vars() — still sees the object exactly as before.

Beyond operators

The class is a normal PHP object too:

Roadmap

Tracked as GitHub issues — contributions welcome:

• Array-style row access — $matrix[0] and $matrix[0][1] via the read_dimension handler
• count($matrix) — row count through Countable, installed at the engine level
• foreach iteration — row-by-row traversal via the get_iterator handler
• Friendly var_dump() — a get_debug_info handler that prints the matrix instead of its internals
• FFI BLAS backend — hand multiplication off to a real BLAS library for performance, keeping the pure-PHP path as the fallback

Contributing

The repository ships an agent/contributor contract in CLAUDE.md — read it before changing anything, especially the section on why the PHP version is pinned.

License

Released under the MIT License.