PHPackages                             php-sdl/sdl3 - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. php-sdl/sdl3

ActivePhp-ext[Utility & Helpers](/categories/utility)

php-sdl/sdl3
============

PHP-Controllable SDL3 Rendering Extension

v0.2.4(1mo ago)06MITCPHP >=8.2CI passing

Since Apr 16Pushed 1mo agoCompare

[ Source](https://github.com/php-sdl/sdl3)[ Packagist](https://packagist.org/packages/php-sdl/sdl3)[ RSS](/packages/php-sdl-sdl3/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (6)Used By (0)

php-sdl3
========

[](#php-sdl3)

[![PHP](https://camo.githubusercontent.com/c43902a50e55ff766fc179e27d9b9a292ef8fcadbdd4d855bb077a334e2f9b46/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135253230382e322d3737376262343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net)[![SDL3](https://camo.githubusercontent.com/0d60227c13873647c269a604bb58bab7866996600408cd565817dcc32b4e3cd0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53444c332d254532253839254135253230332e342e302d316434656438)](https://www.libsdl.org/)[![Built with Zephir](https://camo.githubusercontent.com/8e72a9e9874ec036e66f84af12bd028857d1f200674b7acaa9eb97271a123f7c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6275696c74253230776974682d5a65706869722d666636613030)](https://zephir-lang.com/)[![Platform](https://camo.githubusercontent.com/37c663164df6eec24d0327668403be1782ab3245cf57963be37d9b6873a823a8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f706c6174666f726d2d6c696e75782532302537432532306d61634f532d6c6967687467726579)](#requirements)[![License: MIT](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](#license)

> PHP extension for SDL3 — built with [Zephir](https://zephir-lang.com/), installable via [PHP PIE](https://github.com/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
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
    - [Via PHP PIE (recommended)](#via-php-pie-recommended)
    - [Platform installers](#platform-installers)
    - [Manual build with `phpize`](#manual-build-with-phpize)
- [Verifying the install](#verifying-the-install)
- [Quick start](#quick-start)
- [API reference](#api-reference)
- [License](#license)

---

Requirements
------------

[](#requirements)

ComponentMinimum versionNotesPHP8.2ZTS and NTS builds both supported.SDL33.4.0Must be discoverable via `pkg-config sdl3` or the usual search paths.OSLinux / macOSWindows is not currently supported.CompilerC11 toolchain`gcc`, `clang`, or Apple Clang.`php-dev` / `phpize`matches PHPRequired for any build path that is not PIE.Tested on macOS (Apple Silicon + Intel), Debian Trixie, Raspberry Pi OS (arm64 / armhf), and NVIDIA JetPack 6 (Jetson Orin).

---

Installation
------------

[](#installation)

### Via PHP PIE (recommended)

[](#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

[](#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`

[](#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
---------------------

[](#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
-----------

[](#quick-start)

```