Search by

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

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

0.11.x-dev 2026-11-19 13:37 UTC

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

CI Packagist PHP License Platform PIE

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 phpize and php-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 with R_ERROR_BACKEND; R_BACKEND_NULL always 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).