README

PHP extension for SDL3 — built with Zephir, installable via PHP PIE.

sdl3 exposes SDL3's core, video, render, surface, timer, and event APIs to PHP 8.2+ as a set of namespaced classes under Sdl3\SDL\…. The extension links against the system libSDL3, so it is as fast as a native SDL3 program and supports both hardware-accelerated windows and the headless software renderer.

Table of contents

• Requirements
• Installation
  • Via PHP PIE (recommended)
  • Platform installers
  • Manual build with phpize
• Verifying the install
• Quick start
• API reference
• License

Requirements

Tested on macOS (Apple Silicon + Intel), Debian Trixie, Raspberry Pi OS (arm64 / armhf), and NVIDIA JetPack 6 (Jetson Orin).

Installation

Via PHP PIE (recommended)

PIE reads the php-ext block from composer.json and runs the full build pipeline (phpize → configure → make → install) on your behalf:

pie install php-io-extensions/sdl3

PIE will invoke the --enable-sdl3 configure option automatically. Make sure SDL3 ≥ 3.4.0 is already installed on the system (see the platform installers below if it is not).

Platform installers

Three installer scripts live at the repository root. They install SDL3 if it is missing, then build and enable the extension for every available PHP SAPI.

macOS (Homebrew):

bash install-macos.sh

Debian Trixie / Raspberry Pi OS (amd64, arm64, armhf):

bash install-debian-trixie.sh

JetPack 6 / Ubuntu 22.04 (builds SDL3 from source, since apt ships no compatible version):

bash install-jetpack6.sh

Each script writes a full build log to ./build.log and prints concise failure diagnostics if anything goes wrong.

Manual build with phpize

For full control, build from the pre-generated C source in ext/:

cd ext
phpize
./configure --enable-sdl3
make -j"$(nproc 2>/dev/null || sysctl -n hw.logicalcpu)"
sudo make install

Then enable it for the CLI (and any other SAPI you use) by adding extension=sdl3.so to the appropriate php.ini file, or drop a file into your distribution's conf.d directory:

; /etc/php/8.3/cli/conf.d/20-sdl3.ini
extension=sdl3.so

If SDL3 is installed in a non-standard prefix, export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig (or the equivalent) before running ./configure.

Verifying the install

Run the bundled proof-of-work script — it exercises the full surface and software-renderer pipeline headlessly, so it works without a display server:

php examples/proof_of_work.php

Expected tail of the output:

── Summary ──
  All checks passed — sdl3 extension is working correctly.

A one-liner sanity check:

php -r 'echo Sdl3\SDL\SDL::SDLGetPlatform(), PHP_EOL;'

Quick start

<?php
use Sdl3\SDL\SDL;
use Sdl3\SDL\Video\SDLVideo;
use Sdl3\SDL\Render\SDLRender;
use Sdl3\SDL\Events\SDLEvents;

const SDL_INIT_VIDEO = 0x20;
const SDL_EVENT_QUIT = 0x100;

SDL::SDLInit(SDL_INIT_VIDEO);

[$window, $renderer] = array_values(
    SDLVideo::SDLCreateWindowAndRenderer('Hello SDL3', 640, 480, 0)
);

$running = true;
while ($running) {
    while (($ev = SDLEvents::SDLPollEvent()) !== null) {
        if (($ev['type'] ?? 0) === SDL_EVENT_QUIT) {
            $running = false;
        }
    }

    SDLRender::SDLSetRenderDrawColor($renderer, 30, 30, 60, 255);
    SDLRender::SDLRenderClear($renderer);
    SDLRender::SDLSetRenderDrawColor($renderer, 255, 200, 0, 255);
    SDLRender::SDLRenderDebugText($renderer, 20.0, 20.0, 'Hello from PHP + SDL3!');
    SDLRender::SDLRenderPresent($renderer);
}

SDLRender::SDLDestroyRenderer($renderer);
SDLVideo::SDLDestroyWindow($window);
SDL::SDLQuit();

See examples/proof_of_work.php for a headless surface/renderer example.

API reference

All classes live under the Sdl3\SDL namespace. The PHP stubs that drive your IDE's autocomplete are published under ide/0.2.0/ — this reference mirrors them exactly.

Sdl3\SDL\SDL — lifecycle, version, platform

SDLGetVersion() returns SDL's packed integer: major = v / 1_000_000, minor = (v / 1_000) % 1_000, patch = v % 1_000.

Sdl3\SDL\SDLError — error handling

Sdl3\SDL\Surface\SDLSurface — surfaces & pixel operations

SDLCreateSurface returns ['ptr' => int, 'w' => int, 'h' => int, 'pitch' => int, …]. SDLReadSurfacePixels returns ['pixels_data' => int[], …] — one packed integer per pixel, row-major.

Sdl3\SDL\Render\SDLRender — renderer & drawing primitives

Sdl3\SDL\Video\SDLVideo — window management

SDLCreateWindowAndRenderer returns ['window' => int, 'renderer' => int, …].

Sdl3\SDL\Timer\SDLTimer — timing utilities

Sdl3\SDL\Events\SDLEvents — event queue

Each event array always carries a numeric type key matching the SDL_EVENT_* enum.

Sdl3\SDL\Events\SDLCategories — event filtering & metadata

Sdl3\SDL\Events\SDLKeyboard — keyboard input & text entry

Sdl3\SDL\Events\SDLMouse — mouse devices, cursors, event arms

Sdl3\SDL\Events\SDLDisplayEvents — displays & display modes

Sdl3\SDL\Events\SDLClipboardEvents — clipboard & primary selection

Sdl3\SDL\Events\SDLDropEvents — drag-and-drop payloads

Sdl3\SDL\Events\SDLEventWatch — filters & watchers

Sdl3\SDL\Events\SDLQuit — quit event payload

Supporting / reserved classes

These classes are part of the public surface but currently ship without methods; they are reserved for upcoming SDL3 subsystem bindings:

• Sdl3\SDL\SDLAssert
• Sdl3\SDL\SDLList
• Sdl3\SDL\SDLLog
• Sdl3\SDL\SDLProperties
• Sdl3\SDL\SDLUtils
• Sdl3\SDL\Events\SDLKeymap
• Sdl3\SDL\Events\SDLScancodeTables
• Sdl3\SDL\Events\SDLWindowEvents

License

MIT © Project Saturn Studios, LLC.