php-io-extensions/cuda

PHP-Controllable CUDA Runtime + OpenGL interop extension

0.7.3 2026-08-10 18:40 UTC

Requires

• php: >=8.2

MIT

• Project Saturn Studios, LLC

Published on Packagist.org on 2026-08-10 18:43 UTC

Extension name: ext-cuda

Supports Zend Thread Safety (ZTS): ✅

Supports non-Thread Safe mode (NTS): ✅

Supported operating systems: linux

Configure flags:

• --enable-cuda Enable the cuda extension (CUDA Runtime/Driver + OpenGL interop)

README

PHP extension for the CUDA Runtime API plus CUDA–OpenGL interop — built with Zephir, installable via PHP PIE.

cuda exposes CUDA Runtime device, memory, stream, and event APIs to PHP 8.2+ as namespaced static methods under Cuda\Cuda\Cuda, plus thin data objects (CudaDevicePtr, CudaHostPtr, CudaStream, CudaEvent, CudaGraphicsResource) that store opaque native pointers in public fd.

Cuda\Cuda\CudaGL adds in-package CUDA–GL interop (PBO/texture register/map), an embedded plasma PTX kernel (no nvcc for consumers), and minimal present helpers. Windowing stays in peer extensions (sdl3 / glfw).

This is not CudaGraphics-PHP (custom draw/particle kernels). Token constants (cudaSuccess, memcpy kinds, …) belong in a companion microscrap package, not in this extension.

Requirements

Component	Minimum version	Notes
PHP	8.2	ZTS and NTS builds both supported.
CUDA Toolkit	12.0+	Runtime + Driver + cuda_gl_interop.h (Jetson CUDA 13.2 OK).
OpenGL	desktop GL	Linked as -lGL for interop/present.
OS	Linux / Jetson	aarch64 + x86_64 Linux. Darwin/Windows not supported.
Compiler	C11 toolchain	gcc or clang.
php-dev / phpize	matches PHP	Required for any build path that is not PIE.
nvcc	maintainers only	Regenerating embedded PTX — not required for PIE installs.

Installation

Via PHP PIE (recommended)

export CUDA_HOME=/usr/local/cuda   # if not already the default
pie install php-io-extensions/cuda

PIE builds the committed ext/ tree with --enable-cuda. No Zephir. No nvcc.

Platform installer (Jetson / JetPack)

export CUDA_HOME=/usr/local/cuda
bash install-jetpack6.sh

Manual build with Zephir (maintainers)

export CUDA_HOME=/usr/local/cuda
bash scripts/prepare-ext.sh   # zephir generate + portable config.m4 + REGISTER fixup
cd ext && phpize && ./configure --enable-cuda && make
php -n -d extension=modules/cuda.so --ri cuda

Verifying the install

php -m | grep cuda
php --ri cuda
php examples/proof_of_work.php

Quick start

<?php
use Cuda\Cuda\Cuda;

$count = Cuda::cudaGetDeviceCount();
Cuda::cudaSetDevice(0);
$props = Cuda::cudaGetDeviceProperties(0);

$dev = Cuda::cudaMalloc(1024);
Cuda::cudaMemcpyHtoD($dev, random_bytes(1024), 1024);
$back = Cuda::cudaMemcpyDtoH($dev, 1024);
Cuda::cudaFree($dev);

Examples

# Headless smoke
php examples/proof_of_work.php

# Windowed GPU-owned framebuffer + Quit (needs sdl3 + display)
DISPLAY=:1 CUDA_PROOF_SECONDS=40 php examples/proof_menu.php

API surface

Class	Namespace	Role
Cuda	Cuda\Cuda	Static Runtime API (device, error, memory, stream, event)
CudaGL	Cuda\Cuda	CUDA–GL interop, embedded plasma launch, present helpers
CudaDevicePtr	Cuda\Cuda	Device allocation DTO (fd, size)
CudaHostPtr	Cuda\Cuda	Pinned host allocation DTO (fd, size)
CudaStream	Cuda\Cuda	Stream DTO (fd, flags)
CudaEvent	Cuda\Cuda	Event DTO (fd, flags)
CudaGraphicsResource	Cuda\Cuda	Interop resource DTO (fd, glBuffer, size)

fd === 0 means none / freed. Callers own allocations until cudaFree / cudaFreeHost / cudaStreamDestroy / cudaEventDestroy / CudaGL::unregister. Do not cudaFree a device pointer obtained from CudaGL::map.

IDE stubs: ide/0.7.2/Cuda/.

License

MIT © Project Saturn Studios, LLC.