[lisachenko]

Delivers the roadmap's "FFI BLAS backend" item as an interchangeable driver architecture: the operators stay exactly where they are, the arithmetic behind them becomes pluggable. $logits = $input * $weights + $bias now runs on OpenBLAS or a GPU while remaining ordinary PHP.

Following review, the storage model was rewritten twice. First a Matrix became a native float64 buffer, which removed the marshalling the accelerated drivers paid on every operation — but made the pure-PHP driver walk FFI\CData, two to three times slower than the array loops it replaced. So now storage follows the driver: native buffers under blas/clblast, PHP float arrays under php, each driver computing on the form it reads fastest. The suite passes under every backend.

⚠️ BREAKING CHANGE

Matrix cells are float64 only. Integers are still accepted as input and stored as the doubles they convert to — numpy.array([[1, 2]]) reporting dtype=float64 is the same bargain. Whether those doubles sit in a double[rows * columns] buffer or in a list of rows of PHP floats depends on the driver active when the matrix is built; the values are identical either way.

(new Matrix([[1, 2]]) + new Matrix([[3, 4]]))->toArray();
// before: [[4, 6]]      after: [[4.0, 6.0]]
echo new Matrix([[1, 2]]);   // still "[1, 2]" — integral floats stringify without decimals

Removed / changed	Replacement
Matrix::asFloat()	gone — every matrix is already float64
@template-covariant T of int|float, Matrix<int>	gone — there is one cell type
BackendInterface with six array operations	BackendInterface is the root (isAvailable()); a driver implements BufferBackendInterface (FFI\CData in, fresh buffer out) or ArrayBackendInterface (float rows in, float rows out)
Backends::resolveFor(bool)	Backends::resolve() — returns the storage-typed driver, cached until the selection changes
Backends::PHP / BLAS / CLBLAST / AUTO constants	Driver string-backed enum; Backends::active() returns it for built-ins

Out-of-tree drivers declare their storage by picking one of the two contracts; Backends::use() rejects a driver that implements neither. Two obligations come with either: operands are read-only (a buffer kernel that accumulates into an argument, like daxpy, copies it first) and the result is freshly computed — that is also what makes the automatic fallback safe to re-run.

Architecture

Matrix keeps the validation, the dimension guards and the engine hooks; it asks a registry which driver should compute and hands it the operands in the storage that driver declares. Drivers never see a Matrix.

Driver	Runs on	Storage	Uses
php	interpreter	PHP float arrays	the original foreach loops, verbatim, same summation order
blas	CPU	native buffers	OpenBLAS cblas_dgemm / cblas_daxpy / cblas_dscal called directly on the stored buffers
clblast	GPU	native buffers	CLBlast over OpenCL — NVIDIA, AMD, Intel iGPUs, or the CPU through PoCL

Backends::available();        // ['php', 'blas'] — probed, not guessed
Backends::use(Driver::Blas);  // catchable at selection time
Backends::active();           // Driver::Blas
Backends::register('cublas', static fn (): BackendInterface => new CuBlasBackend());
Backends::use('cublas');      // third-party drivers keep their registered string

NATIVE_PHP_MATRIX_BACKEND=php|blas|clblast|auto pins one process-wide, NATIVE_PHP_MATRIX_CL_DEVICE=gpu|cpu|all picks the OpenCL device type.

Semantics decided here

• Everything is float64; storage follows the driver. The constructor picks the form of the active driver and is the only place a value changes type — writing an int into a double slot (buffer) or appending it as (float) (rows), in the same pass that validates it. No cast loop anywhere else; the array multiplication's accumulator starts at 0.0.
• Zero marshalling when operands match their driver — which is always, unless the driver changed after they were built. Buffer operands are handed to kernels as the pointers they are; array operands are walked by foreach. A mismatched operand is converted once, in bulk (pack/FFI::memcpy, FFI::string/unpack — no PHP loop over cells), and the result takes the computing driver's form.
• Hook safety. Everything reachable from an operation runs inside an FFI callback, where a thrown exception is Fatal error: Throwing from FFI callbacks is not allowed. Selection is validated eagerly, in userland; availability is reported from a non-throwing isAvailable(); under auto a driver that fails mid-operation is caught and recomputed on the array-native PHP driver.
• Availability is proven, not guessed. Probing loads the library and runs a real 1×1 multiplication.
• auto is boring on purpose. OpenBLAS (on buffers) whenever it is loadable, for every operation, pure PHP (on arrays) otherwise, and never a GPU on its own.
• equals() is bit-exact in every form. memcmp for two buffers, packed doubles for two arrays, a buffer conversion for mixed operands — all documented as stricter than == for -0.0 and NAN.
• Device memory is released explicitly. cl_mem is not reference counted by PHP: every buffer is freed in a finally.
• Only LP64 OpenBLAS sonames are probed — an ILP64 build would silently corrupt every dimension argument.

Tests

The suite is one behaviour per .phpt, all with master's two-line --INI-- (ffi.enable=1, opcache.jit=off). Every cell expectation is a float, which is what lets the whole suite pass under every pinned backend — default, php, blas and clblast. Tests that existed solely to describe integer semantics (testAutoKeepsIntMatricesOnPhpBackend, the asFloat() test) are removed; testMatrixStoresFloat64 replaces them.

Storage-following-driver is covered by testStorageFollowsDriver, testCanOperateAcrossDriverSwitch (operations and == on matrices built under the other driver), testComparesCellsBitExactly, testAutoRecomputesInPhpWhenAcceleratedDriverFails (a failing buffer driver under auto, recomputed on arrays) and testFailsOnSelectingBackendWithoutStorage. testKeepsDefaultDebugOutput now pins NATIVE_PHP_MATRIX_BACKEND=php, because what the property table shows depends on the driver — a test whose output exposes storage must not depend on whether OpenBLAS is installed.

Determinism is by construction: integral-valued float fixtures with small dimensions keep every partial sum exactly representable, which is what lets testBlasMatchesPhpBackendResults and testClblastMatchesPhpBackendResults compare an 8×8 product exactly against the interpreted one despite a different summation order. Divisions use power-of-two divisors, because BLAS scales by the reciprocal.

CI

• tests (8.4, 8.5, 8.6): installs the acceleration libraries, runs the suite under default routing and under NATIVE_PHP_MATRIX_BACKEND=php.
• gpu-path (8.4, 8.5, 8.6): runs composer test in full on PoCL's CPU device with NATIVE_PHP_MATRIX_BACKEND=clblast.
• static-analysis now also runs on 8.6; coding-standards stays on 8.4. The 8.6 legs are set up exactly as z-engine's own CI sets up its 8.6 line (plain php-version: '8.6', same ini values) and are required, as they are there; PHPStan stays at level max with no baseline, and every ignore is a genuine FFI modelling gap scoped to a path with an identifier and a comment — the pure-PHP driver no longer needs any, it computes on typed arrays.

Benchmarks

composer bench times the whole PHP-level operation, from the operator to a finished Matrix, with the operands built under the driver being measured.

Operation	Size	php	blas	clblast	blas speed-up	clblast speed-up
Multiplication $a * $b	64×64	6.42 ms (0.1 GFLOP/s)	0.04 ms (12.6 GFLOP/s)	0.46 ms (1.1 GFLOP/s)	×154.2	×13.9
Multiplication $a * $b	128×128	31.41 ms (0.1 GFLOP/s)	0.08 ms (50.5 GFLOP/s)	0.71 ms (5.9 GFLOP/s)	×378.5	×44.0
Multiplication $a * $b	256×256	245.67 ms (0.1 GFLOP/s)	0.32 ms (105.5 GFLOP/s)	2.11 ms (15.9 GFLOP/s)	×772.2	×116.6
Multiplication $a * $b	512×512	2,007.76 ms (0.1 GFLOP/s)	2.35 ms (114.0 GFLOP/s)	17.41 ms (15.4 GFLOP/s)	×852.9	×115.3
Multiplication $a * $b	1024×1024	15,608.82 ms (0.1 GFLOP/s)	19.64 ms (109.4 GFLOP/s)	124.43 ms (17.3 GFLOP/s)	×794.8	×125.4

Element-wise operations:

Operation	Size	php	blas	clblast	blas speed-up	clblast speed-up
Addition $a + $b	64×64	0.10 ms	0.03 ms	0.50 ms	×3.2	×0.2
Addition $a + $b	512×512	4.98 ms	1.27 ms	5.53 ms	×3.9	×0.9
Scaling $a * 2.5	64×64	0.08 ms	0.04 ms	0.45 ms	×1.8	×0.2
Scaling $a * 2.5	512×512	3.39 ms	1.15 ms	1.96 ms	×2.9	×1.7

The php column is the original array loops again, so every speed-up above is measured against the interpreter at its best. Against the previous buffer-only storage, where the interpreter had to walk FFI\CData — same container, same --backends=php --sizes=64,128,256,512 invocation:

php driver	buffer storage (FFI\CData)	array storage
Multiplication 128×128	58.77 ms	27.72 ms	×2.1
Multiplication 256×256	484.95 ms	228.49 ms	×2.1
Multiplication 512×512	4,146.31 ms	1,848.79 ms	×2.2
Addition 512×512	9.46 ms	5.12 ms	×1.8
Scaling 512×512	6.76 ms	3.43 ms	×2.0

The accelerated drivers lose nothing for it: their matrices are still buffers, handed to the kernels without a conversion.

_{PHP 8.5.11, Linux x86_64, Intel® Xeon® @ 2.10 GHz (shared cloud container, no GPU), OpenBLAS 0.3.26, CLBlast 1.6.2 on PoCL 5.0 with NATIVE_PHP_MATRIX_CL_DEVICE=cpu. Median of 5, one warm-up discarded. The clblast column is a portability proof, not a GPU benchmark.}

Docs

README documents the two storage forms, the Driver enum, the two driver contracts and the single remaining routing rule, with the tables above. CLAUDE.md's backend map lists the storage contracts, the float64 rule becomes "everything is float64, and storage follows the driver", and the test conventions require float expectations, a suite that stays green under every pinned backend, and a pinned backend for any test whose output exposes storage.

Merged with master

Master's stable z-engine requirement (~8.4.2 || ~8.5.0, no root stability flags) and its two-line --INI-- convention are merged in; every test this PR adds follows it. Dropping the E_DEPRECATED suppression surfaced a real deprecation in this PR's code — static FFI::new() — fixed by allocating from an FFI::cdef() scope rather than restoring the suppression.

PHP 8.6 (z-engine 8.6.x-dev)

z-engine's master is its 8.6 line ("php": "~8.6.0", branch-aliased 8.6.x-dev), so PHP 8.6 is added together with the z-engine line built for it: the requirement is now ~8.4.2 || ~8.5.0 || 8.6.x-dev, still exactly one line per running minor, and the Core::init() guard is untouched.

• The explicit dev constraint is its own root stability flag, so this package's installs resolve master on 8.6 without minimum-stability: dev. That flag covers the whole package, though, and would otherwise let PHP 8.5 resolve the 8.5.x-dev branch over the 8.5.0 tag — the root now carries "prefer-stable": true, which keeps 8.4 and 8.5 on their stable tags.
• Stability flags do not propagate: until z-engine tags 8.6, a consumer on PHP 8.6 must require lisachenko/z-engine:8.6.x-dev at its own root (README Requirements/Installation say so). 8.4/8.5 consumers need nothing extra.
• When z-engine tags 8.6, 8.6.x-dev becomes ~8.6.0 and prefer-stable goes, in a single change (CLAUDE.md Dependency policy).

Verification

• Suite green on PHP 8.5.11 in all four modes — default, =php, =blas, =clblast on PoCL — 42 tests each.
• CI green on the head commit: tests and GPU path on PHP 8.4, 8.5 and 8.6 (8.6.0-dev nightly, z-engine dev-master; 8.4 and 8.5 still lock the 8.4.2 / 8.5.0 tags), PHPStan level max (no baseline) on all three, coding standards; composer cs:fix idempotent.
• No segfaults or bus errors at any point.

🤖 Generated with Claude Code

https://claude.ai/code/session_017HAT4khAiANxtSUrqFSeQE