feat(backend): CPU/GPU acceleration drivers for matrix arithmetic

[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: a Matrix is now a native float64 buffer, and drivers receive that buffer rather than a PHP array. That removed the marshalling this PR originally had to apologise for, so auto can accelerate every operation and the suite passes under every backend.

⚠️ BREAKING CHANGE

Matrix cells are float64 only. A matrix owns one contiguous, row-major double[rows * columns] allocation instead of a PHP array of rows. 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.

(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 array operands and return	FFI\CData buffers in, a freshly allocated buffer out
Backends::resolveFor(bool)	Backends::resolve() — routing no longer inspects operand types
Backends::PHP / BLAS / CLBLAST / AUTO constants	Driver string-backed enum; Backends::active() returns it for built-ins

Out-of-tree drivers must be updated to the buffer contract. Two obligations come with it: operands are read-only (a kernel that accumulates into an argument, like daxpy, copies it first) and the result is a fresh allocation — 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 operand buffers. Drivers never see a Matrix.

Driver	Runs on	Uses
php	interpreter	the original loops, now over buffer offsets, same summation order
blas	CPU	OpenBLAS cblas_dgemm / cblas_daxpy / cblas_dscal called directly on the stored buffers
clblast	GPU	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. The constructor is the only place a value changes type, and it does so by writing an int into a double slot while it validates — FFI converts natively, so there is no userland cast loop anywhere in the package.
• Zero marshalling. Operands are handed to kernels as the pointers they already are. The only copy left is the one accumulating kernels force: a single memcpy into the result buffer, instead of a cell-by-cell conversion of both operands in and the result out.
• 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 in pure PHP.
• Availability is proven, not guessed. Probing loads the library and runs a real 1×1 multiplication.
• auto is boring on purpose. OpenBLAS whenever it is loadable, for every operation, pure PHP otherwise, and never a GPU on its own. Both former exceptions — the integer path and the element-wise penalty — no longer exist.
• equals() is a memcmp. Bit-exact over both buffers, 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 the mandatory three-line --INI--. Every cell expectation is now a float, which is what finally lets the whole suite pass under every pinned backend — default, php, blas and clblast — instead of only under default routing. Tests that existed solely to describe integer semantics (testAutoKeepsIntMatricesOnPhpBackend, the asFloat() test) are removed; testMatrixStoresFloat64 replaces them.

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): installs the acceleration libraries, runs the suite under default routing and under NATIVE_PHP_MATRIX_BACKEND=php.
• gpu-path (8.4, 8.5): now takes its PHP version from a matrix like every other job, and runs composer test in full on PoCL's CPU device instead of naming the CLBlast files — the workaround that existed only because pinning a backend used to break integer expectations.
• Dependabot already tracks the github-actions ecosystem weekly alongside the daily composer updates, so the action pins here keep updating on their own.
• static-analysis and coding-standards unchanged; 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.

Benchmarks

composer bench times the whole PHP-level operation, from the operator to a finished Matrix.

Operation	Size	php	blas	clblast	blas speed-up	clblast speed-up
Multiplication $a * $b	64×64	10.71 ms (0.0 GFLOP/s)	0.06 ms (8.8 GFLOP/s)	0.75 ms (0.7 GFLOP/s)	×180.7	×14.2
Multiplication $a * $b	128×128	83.63 ms (0.1 GFLOP/s)	0.15 ms (27.9 GFLOP/s)	1.31 ms (3.2 GFLOP/s)	×557.2	×63.8
Multiplication $a * $b	256×256	670.35 ms (0.1 GFLOP/s)	0.46 ms (73.6 GFLOP/s)	3.47 ms (9.7 GFLOP/s)	×1,471.3	×193.0
Multiplication $a * $b	512×512	5,413.33 ms (0.0 GFLOP/s)	3.59 ms (74.8 GFLOP/s)	21.76 ms (12.3 GFLOP/s)	×1,508.2	×248.7
Multiplication $a * $b	1024×1024	43,561.10 ms (0.0 GFLOP/s)	22.67 ms (94.7 GFLOP/s)	159.40 ms (13.5 GFLOP/s)	×1,921.4	×273.3

Element-wise operations — the caveat this PR used to carry, now gone:

Operation	Size	php	blas	clblast	blas speed-up	clblast speed-up
Addition $a + $b	64×64	0.21 ms	0.05 ms	0.71 ms	×4.0	×0.3
Addition $a + $b	512×512	13.14 ms	2.15 ms	7.97 ms	×6.1	×1.6
Scaling $a * 2.5	64×64	0.16 ms	0.07 ms	0.53 ms	×2.3	×0.3
Scaling $a * 2.5	512×512	10.23 ms	1.82 ms	2.92 ms	×5.6	×3.5

Against the previous array-backed storage, on the same container:

	before	after
Addition 512×512, blas	25.27 ms (×0.3 — slower than the interpreter)	2.15 ms (×6.1)
Scaling 512×512, blas	24.45 ms (×0.3)	1.82 ms (×5.6)
Multiplication 1024×1024, blas	113.61 ms (18.9 GFLOP/s)	22.67 ms (94.7 GFLOP/s)

The php column moved the other way — walking FFI\CData costs more than walking a PHP array — so the ratios are large partly because the fallback got slower. That is the deliberate trade: the driver that needs no library at all absorbs the cost so every other driver stops paying for conversion.

_{PHP 8.5.9, Linux x86_64, Intel® Xeon® @ 2.80 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 float64 storage, the Driver enum, and the single remaining routing rule; its crossover section is replaced by an explanation of why the crossover is gone. CLAUDE.md's generics section becomes the float64 storage rule, the backend rules gain the read-only-operands contract, and the test conventions require float expectations and a suite that stays green under every pinned backend.

Verification

• Suite green on PHP 8.5.9 in all four modes — default, =php, =blas, =clblast on PoCL — 37 tests each.
• composer phpstan (level max, no baseline) and composer cs:check clean; composer cs:fix idempotent.
• No segfaults or bus errors at any point.

🤖 Generated with Claude Code

https://claude.ai/code/session_017HAT4khAiANxtSUrqFSeQE

---

Generated by Claude Code