php-io-extensions / thorvg
1:1 PHP bindings of ThorVG 1.1.3's C API, a 2D vector graphics engine (shapes, paints, scenes, gradients, masks, effects, text, SVG and image loading, video, GIF saving) on its CPU renderer, compiled into the extension
Package info
github.com/php-io-extensions/thorvg
Language:C++
Type:php-ext
Ext name:ext-thorvg
pkg:composer/php-io-extensions/thorvg
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-17 14:58:38 UTC
README
ext-thorvg
ThorVG 1.1.3's C API bound 1:1 into PHP 8.4+, with the library compiled in
A 2D scene in software is more than filled paths: shapes with strokes, dashes and trims, linear, radial and conic gradients, scenes that group paints and blur, shadow or tint them, alpha and luma masks, blend modes, pictures loaded from SVG, PNG, JPG or WebP, text laid out from a TrueType or OpenType font, and frames saved as an animated GIF.
ThorVG does all of that in one engine: a retained scene of reference-counted paints rendered by a SIMD CPU rasteriser (NEON on ARM, AVX2 on x86-64) on its own worker threads, with partial redraw, into 32-bit pixels with straight or premultiplied alpha.
The only problem? PHP can't reach it. This extension binds every function of ThorVG's C API (thorvg_capi.h) one to one under the C names, with ThorVG compiled into the module from an unchanged copy of the upstream tag, so there is nothing to install from the system. Handles are objects that keep what ThorVG still uses alive, structs are typed classes, and every argument ThorVG would trust blindly is checked first. No defaults, no composites, no opinions: what ThorVG documents is what you call.
Basic usage
<?php // A red rounded square under a translucent blue disc, drawn into a 64×64 RGBA string. tvg_engine_init(0); $pixels = str_repeat("\0", 64 * 64 * 4); $canvas = tvg_swcanvas_create(TVG_ENGINE_OPTION_DEFAULT); tvg_swcanvas_set_target($canvas, $pixels, 64, 64, 64, TVG_COLORSPACE_ABGR8888S); // straight RGBA bytes $square = tvg_shape_new(); tvg_shape_append_rect($square, 8, 8, 48, 48, 6, 6, true); tvg_shape_set_fill_color($square, 220, 40, 40, 255); $disc = tvg_shape_new(); tvg_shape_append_circle($disc, 40, 40, 16, 16, true); tvg_shape_set_fill_color($disc, 30, 90, 230, 160); tvg_canvas_add($canvas, $square); tvg_canvas_add($canvas, $disc); tvg_canvas_draw($canvas, true); tvg_canvas_sync($canvas); // drawing may run on worker threads: read pixels after sync echo bin2hex(substr($pixels, (20 * 64 + 20) * 4, 4)), "\n"; // dc2828ff echo bin2hex(substr($pixels, (40 * 64 + 40) * 4, 4)), "\n"; // 64479efe
Requirements
- PHP 8.4 or newer, NTS or ZTS, with
phpizeandphp-config. - A C and C++ compiler.
- No system libraries. On macOS the media loader links AVFoundation, which ships with the system.
# Debian, Ubuntu, Raspberry Pi OS sudo apt install build-essential php8.4-dev # macOS: Xcode Command Line Tools, and Homebrew's PHP ships phpize and php-config xcode-select --install
Installation
With PHP PIE (recommended)
pie install php-io-extensions/thorvg
Manually (install script)
git clone https://github.com/php-io-extensions/thorvg.git cd thorvg ./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/thorvg.git cd thorvg phpize ./configure --enable-thorvg make -j"$(nproc 2>/dev/null || sysctl -n hw.ncpu)" sudo make install
Then add extension=thorvg.so to your php.ini, or to a file in the scan directory php --ini reports.
Verify
$ php --ri thorvg thorvg thorvg support => enabled Version => 0.11.x ThorVG version => 1.1.3 ThorVG commit => 589bc4120f2097fb1b135e552c2ef39f6581612b ThorVG modules => cpu engine, svg, png, jpg, webp, ttf, otf, media, gif saver
API
All 190 functions of ThorVG's C API, under their C names, plus two binding additions: tvg_swcanvas_get_alpha() returns the alpha byte of every pixel of a 32-bit canvas buffer in one call (a shape drawn in opaque white on a cleared buffer leaves its coverage there), and tvg_swcanvas_get_target_address() returns the address of the string a canvas draws into, so other code can draw into the same memory. A third, tvg_shape_get_stroke_outline(), returns the outline of a shape's stroke from ThorVG's own CPU stroker, in the shape's own coordinates and in the same form as tvg_shape_get_path() (width, cap, join and miter limit applied; dash and trim not). ThorVG's API keeps a stroke as settings only, so this one calls ThorVG internals (cpu_engine/tvgSwStroke.cpp) and a ThorVG update may change it. The full rules are in the design spec.
What is compiled in
The CPU engine (partial rendering, task scheduler, NEON or AVX2), the SVG, PNG, JPG, WebP and TTF/OTF loaders, the media loader (AVFoundation on macOS; no backend elsewhere, so tvg_video_* load nothing on Linux), and the GIF saver. Not compiled in: the GL and WebGPU engines and the Lottie loader. Their functions are still bound and answer what ThorVG answers without them: tvg_glcanvas_create(), tvg_wgcanvas_create() and tvg_lottie_animation_new() return null, the rest TVG_RESULT_NOT_SUPPORTED.
Translations
- Constants: every enum value (
TVG_RESULT_*,TVG_COLORSPACE_*,TVG_BLEND_METHOD_*,TVG_PATH_COMMAND_*, …). - Handles (
Tvg_Canvas,Tvg_Paint,Tvg_Gradient,Tvg_Saver,Tvg_Animation,Tvg_Accessor,Tvg_Video) are final classes. A CNULLisnull. The same paint or gradient always comes back as the same object.*_delandtvg_canvas_destroyrelease a handle early; a released handle throwsValueError. - Value structs (
Tvg_Point,Tvg_Matrix,Tvg_Region,Tvg_Color_Stop,Tvg_Text_Metrics,Tvg_Glyph_Metrics,Tvg_WgContext,Tvg_Audio_Info) have one typed property per C field, zero by default. A struct ThorVG fills (tvg_paint_get_transform,tvg_text_get_text_metrics) is written into the object you pass. - Out-parameters are references (
tvg_paint_get_aabb($paint, $x, $y, $w, $h)); arrays ThorVG hands back (tvg_shape_get_path,tvg_gradient_get_color_stops,tvg_canvas_get_dirty_regions,tvg_paint_get_obb) are lists by reference. - Lists stand for a pointer and count; the count stays its own argument and may not exceed the list.
- Memory:
tvg_swcanvas_set_target's buffer is a string ThorVG draws into in place (build it at run time, e.g.str_repeat(); a literal is refused) or an address.tvg_picture_load_raw,tvg_picture_load_dataandtvg_font_load_datatake a string or an address; withoutcopy, a string stays alive until the request ends.void*arguments are addresses. tvg_text_get_glyph_metrics'snextis the byte offset of the next character in$ch.tvg_paint_get_mask_method'stargetis a reference you receive the mask target in: the header types it as a paint but documents it[out], and ThorVG writes through it.
Lifetimes
Paints are reference-counted: each Tvg_Paint object holds one reference, so a paint you drop lives on in the canvas or scene it was added to, and one you hold outlives them. tvg_paint_ref/tvg_paint_unref adjust ThorVG's count, but unref cannot give back the object's own reference. Setting a gradient hands it to the shape or text: its object is released. tvg_shape_get_gradient and tvg_shape_get_stroke_gradient lend the shape's gradient back; a lent gradient throws once the shape no longer holds it, and cannot be deleted or set elsewhere (tvg_gradient_duplicate it). A canvas keeps its target string and finishes a draw before it is destroyed; a saver keeps the animation it renders until tvg_saver_sync.
Callbacks
tvg_accessor_set takes callable(Tvg_Paint $paint, mixed $data): bool and calls it synchronously for each paint; returning false or throwing stops the walk. The asset and audio resolvers take a callable or null; only the Lottie loader calls them, which this build does not have.
Errors
ThorVG reports failure through TVG_RESULT_* values, which come back as ints. Arguments ThorVG would trust and crash on are refused before it runs: a paint of the wrong type for a tvg_shape_*, tvg_scene_*, tvg_picture_* or tvg_text_* function (TypeError), and an enum or channel out of range, a short buffer, a count past its list, a negative or NaN dash, a mask or clip on the paint itself, NaN or infinite path coordinates (ThorVG's stroker can loop forever on them), or a file path that is not valid UTF-8 (ThorVG's macOS media loader aborts on one) (ValueError). Paths outside open_basedir answer TVG_RESULT_INVALID_ARGUMENT.
Running the test suite
composer install
php -d memory_limit=128M vendor/bin/pest
php -d memory_limit=256M tools/sweep.php # crash sweep: every function, five argument sets, one process each
The text tests use a TrueType font found on the machine (Arial on macOS, DejaVu Sans on Debian) and skip without one.
Security
See SECURITY.md. Images, SVG and fonts are trusted input.
License
MIT for this extension. ThorVG is MIT, lib/thorvg/LICENSE.