php-io-extensions / raven
1:1 PHP bindings of Raven 0.3.0, a retained-mode GUI toolkit in C, compiled into the extension
Package info
github.com/php-io-extensions/raven
Language:C
Type:php-ext
Ext name:ext-raven
pkg:composer/php-io-extensions/raven
Requires
- php: >=8.4
Requires (Dev)
- pestphp/pest: ^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-22 02:26:41 UTC
README
ext-raven
Raven 0.3.0 bound 1:1 into PHP 8.4+, with the toolkit compiled in
An editor, a tool or a control panel needs windows, buttons, lists, trees, text editors and docked panels that lay themselves out, take keyboard and mouse input, and redraw only what changed. Writing that in PHP means a widget tree, a layout engine, text shaping, a renderer and a window system per platform: a GUI toolkit, which is years of work before the first button looks right.
Raven is that toolkit. Oscar Soirey's library is a retained-mode GUI in C: windows hold widget trees, panels place their children, controls report changes through callbacks, interfaces can be written in XML, and a Vulkan renderer draws them on native Cocoa, X11 or Wayland windows. Its layout and painting run on worker and render threads while the application stays on one UI thread.
The only problem? PHP can't reach it. This extension binds every function of Raven.h one to one under the C names, with Raven compiled into the module from an unchanged copy of upstream 0.3.0 (c34466d), so there is nothing to install from the system but libX11 on Linux. Structs are typed classes, callbacks are PHP callables that always run on the PHP thread, sizes and ranges are checked before Raven sees them, and Raven's errors come back through its own RError codes and error callback. No defaults, no composites, no opinions: what Raven documents is what you call.
Basic usage
Build an interface, bind what it does, run the loop:
Rinit(R_BACKEND_VULKAN); $xml = <<<'XML' <VBox Padding="12" Spacing="8"> <Label Text="Name"/> <TextInput Name="name"/> <Button Text="Greet" OnClicked="app.greet"/> </VBox> XML; $window = Rwindow_create('Hello', 480, 200, R_WINDOW_DEFAULT); Rwindow_set_content($window, Rwidget_create_from_xml($xml, strlen($xml))); Raction_bind('app.greet', function (int $sender, ?string $action, mixed $window): void { Rwindow_set_title($window, 'Hello, ' . Rtext_input_get_text(Rwidget_find($window, 'name'))); }, $window); while (Rwait_frame(-1.0)) { } Rshutdown();
The same widgets are built from code with Rwidget_create, Rbutton_create, Rwidget_add_child and the setters of each control. For a test or a server without a display, Rinit_ex(new RInitDesc(backend: R_BACKEND_NULL, headless: R_TRUE)) runs everything without opening a window or drawing.
Requirements
- PHP 8.4 or newer, NTS or ZTS, with
phpizeandphp-config. - A C11 compiler.
- Linux: libX11 headers and
pkg-config. Wayland, D-Bus and the Vulkan loader are opened at run time. - macOS: Xcode Command Line Tools.
- To show windows: a Vulkan loader at run time (MoltenVK on macOS). Without one,
Rinit(R_BACKEND_VULKAN)fails withR_ERROR_BACKEND;R_BACKEND_NULLalways works.
# Debian, Ubuntu, Raspberry Pi OS sudo apt install build-essential pkg-config libx11-dev php8.4-dev # macOS: Xcode Command Line Tools, and Homebrew's PHP ships phpize and php-config xcode-select --install brew install molten-vk vulkan-loader # only to show windows
Installation
With PHP PIE (recommended)
pie install php-io-extensions/raven
Manually (install script)
git clone https://github.com/php-io-extensions/raven.git cd raven ./install-debian-trixie.sh # Debian Trixie, Ubuntu 24.04+, Raspberry Pi OS: the php on PATH ./install-macos.sh # Homebrew php@8.4 and php@8.4-zts ./install-macos.sh /path/to/bin/php # either script takes specific PHP binaries
Manually (phpize)
git clone https://github.com/php-io-extensions/raven.git cd raven phpize ./configure --enable-raven make -j"$(nproc 2>/dev/null || sysctl -n hw.ncpu)" sudo make install
Then add extension=raven.so to your php.ini, or to a file in the scan directory php --ini reports.
Verify
$ php --ri raven raven raven support => enabled Version => 0.11.x Raven version => 0.3.0 Raven commit => c34466db536219f5ed0e026c4286a1ce27887b57 Vulkan-Headers commit => b379292b2ab6df5771ba9870d53cf8b2c9295daf
API
All 1,375 functions of Raven.h but five raw-memory ones (Rmemory_alloc, Rmemory_realloc, Rmemory_free, Rpixels_alloc, Rpixels_free): 1,370 functions, 37 classes, every enumerator and public #define as a constant. The stubs in stubs/ are the reference, one file per Raven header, with that header's comments on the functions; Raven's own headers in lib/raven/include/raven/ document what each call does. 0.3.0 adds Carousel, MapView, Raven Script, tile-view sections, action parameters (RActionContext), and app lifecycle / back handling. A Label with a tooltip takes the hover so the tooltip can show (Rwidget_set_tooltip, and Tooltip="..." in XML).
Translations
| C | PHP |
|---|---|
Rid, Ruint, int, enums, size_t, uint64_t |
int, range-checked to the C type (ValueError) |
float, double |
float |
const char* |
?string; with a size_t after it, the size must not pass the string's end |
int*, float*, double*, Ruint*, const char** |
by-reference parameter, written after the call |
const T*, T* (struct) |
?T, a final class with one typed property per C field; T* is written back |
float[4] field |
array of exactly 4 floats |
const uint8_t* rgba, int width, int height |
string of at least width × height × 4 bytes |
const void* data, size_t size |
string and the size, which must not pass its end |
const double*, const float*, const char* const*, const T* with a count |
array holding at least count elements |
const float* sized by the two preceding ints (Rchart_set_grid) |
array holding at least rows × columns floats |
callback + void* user_data |
?callable + mixed; the callable gets the C arguments with user_data in its C place |
void* user handle (Rwidget_set_user_handle …) |
mixed, held per widget, window, tree item or node |
RPainter* |
RPainter, valid until its paint callback returns |
RActionContext* |
RActionContext, valid until its parameterized-action callback returns |
| Vulkan handles, native window fields | int addresses |
| returned pixels / file contents | ?string, Raven's memory released before return |
Callbacks and threads
Raven runs every widget callback on its UI thread, inside Rdraw_frame, Rwait_frame or Rwait_events; the UI thread is the PHP thread that called Rinit, so callables run directly. An exception a callable throws comes out of the Raven call that ran it, and no other callable runs until then.
Workers and the render thread never enter PHP. Rparallel_for runs every range on the PHP thread before it returns; Rtask_run_async hands its task back to the UI thread with Rtask_post; render-thread callbacks (viewport drawing, the Vulkan queue lock, a custom backend) wait for the PHP thread to serve them, at its next VM interrupt or Raven frame, and take their no-op result if it does not start within the deadline (100 ms for viewport drawing, 5 s otherwise). RInitDesc::$disable_render_thread = R_TRUE keeps rendering on the PHP thread.
The extension keeps each callable while Raven may call it, releases those of destroyed widgets on a sweep, and releases all of them at Rshutdown and at request end (which shuts Raven down if the script did not).
Errors
Arguments that do not fit the C type are a ValueError or TypeError before Raven is called. Using Raven in a process forked after Rinit is an Error. Everything else is Raven's: return values, Rerror_get_last(), and Rerror_set_callback().
Running the test suite
composer install XDEBUG_MODE=off php -d memory_limit=128M vendor/bin/pest
Tests run Raven headless on the null backend: no window opens.
Security
See SECURITY.md.
License
MIT, for the extension. Raven is Apache-2.0 (lib/raven/LICENSE, lib/raven/NOTICE, its third-party notices in lib/raven/THIRD_PARTY.md); the Vulkan headers are Apache-2.0 or MIT (lib/vulkan-headers/LICENSE.md).