Search by

1:1 PHP bindings of Blend2D 0.21.3's C API, a 2D vector graphics engine with JIT-compiled pipelines (paths, strokes, gradients, patterns, images, fonts and text, PNG/JPEG/BMP/QOI codecs, multi-threaded rendering), compiled into the extension with the asmjit it embeds

Package info

github.com/php-io-extensions/blend2d

Language:C++

Type:php-ext

Ext name:ext-blend2d

pkg:composer/php-io-extensions/blend2d

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

0.11.x-dev 2026-11-15 17:16 UTC

This package is auto-updated.

Last update: 2026-11-17 14:52:15 UTC


README

ext-blend2d

Blend2D 0.21.3's C API bound 1:1 into PHP 8.4+, with the library and its JIT compiled in

CI Packagist PHP License Platform PIE

Drawing 2D vector graphics on the CPU fast means more than a scanline loop: anti-aliased paths with both fill rules, strokes with caps, joins and dashes, linear, radial and conic gradients, image patterns, every Porter-Duff and blend mode, text shaped from OpenType fonts, and images read and written as PNG, JPEG, BMP or QOI.

Blend2D does all of that, and compiles its rendering pipelines to machine code at run time with an embedded JIT (asmjit, on x86-64 and ARM64), optionally rendering on worker threads.

The only problem? PHP can't reach it. This extension binds every function of Blend2D's C API one to one under the C names, with Blend2D and asmjit compiled into the module from unchanged copies of the upstream commits, so there is nothing to install from the system. Blend2D's objects are PHP objects with C's lifetime rules, structs are typed classes, and every argument Blend2D would trust blindly is checked first. No defaults, no composites, no opinions: what Blend2D documents is what you call.

Basic usage

<?php
// A red rounded square under a translucent blue disc, drawn into a 64×64 PHP string.
$pixels = str_repeat("\0", 64 * 64 * 4);           // built at run time: Blend2D writes into it
$image = new BLImageCore();
bl_image_init_as_from_data($image, 64, 64, BL_FORMAT_PRGB32, $pixels, 64 * 4, BL_DATA_ACCESS_RW);

$ctx = new BLContextCore();
bl_context_init_as($ctx, $image, null);
bl_context_fill_all_rgba32($ctx, 0xFF000000);
bl_context_fill_geometry_rgba32($ctx, BL_GEOMETRY_TYPE_ROUND_RECT, new BLRoundRect(8, 8, 48, 48, 6, 6), 0xFFDC2828);
bl_context_fill_geometry_rgba32($ctx, BL_GEOMETRY_TYPE_CIRCLE, new BLCircle(40, 40, 16), 0xA01E5AE6);
bl_context_end($ctx);                                // rendering may run on worker threads: read after end

// PRGB32 pixels are premultiplied B, G, R, A bytes on a little-endian CPU.
echo bin2hex(substr($pixels, (20 * 64 + 20) * 4, 4)), "\n"; // 2828dcff
echo bin2hex(substr($pixels, (40 * 64 + 40) * 4, 4)), "\n"; // 9f4765ff

Requirements

  • PHP 8.4 or newer, NTS or ZTS, with phpize and php-config.
  • A C and C++20 compiler: GCC 10+ or Clang 12+ (Debian Trixie's stock g++ and Xcode's clang both qualify).
  • No system libraries.
# 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

A build compiles 178 Blend2D and asmjit sources: about 35 seconds on an 8-core M1 Pro.

Installation

With PHP PIE (recommended)

pie install php-io-extensions/blend2d

Manually (install script)

git clone https://github.com/php-io-extensions/blend2d.git
cd blend2d

./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/blend2d.git
cd blend2d
phpize
./configure --enable-blend2d
make -j"$(nproc 2>/dev/null || sysctl -n hw.ncpu)"
sudo make install

Then add extension=blend2d.so to your php.ini, or to a file in the scan directory php --ini reports.

Verify

$ php --ri blend2d

blend2d

blend2d support => enabled
Version => 0.11.x
Blend2D version => 0.21.3
Blend2D commit => 58ca9460b4138af6e793184682e9324e0a8053b2
asmjit commit => 677a10bac2c24f7e068cf1f9e675bf51c7b534ea
JIT pipelines => enabled

API

772 of the 780 functions Blend2D's C API has on Linux and macOS, under their C names. The 8 left out are the C-variadic and va_list message/format functions (a PHP format string could read or write arbitrary memory; format with sprintf and use bl_runtime_message_out or bl_string_apply_op_data) and the four hooks for implementing new object types in C. The full rules are in the design spec.

Translations

  • Constants: every enum value (BL_FORMAT_*, BL_COMP_OP_*, BL_GEOMETRY_TYPE_*, BL_ERROR_*, …) and BL_VERSION.
  • Cores (BLImageCore, BLPathCore, BLContextCore, … 26 in all) are final classes holding one Blend2D object, with C's lifetime: a new one is uninitialised until its bl_*_init* call, and using it before that throws Error. bl_*_destroy destroys it early; freeing the PHP object destroys it otherwise. clone shares the data copy-on-write (Blend2D's weak copy); BLFileCore, BLRuntimeScopeCore and BLBitSetBuilderCore can't be cloned.
  • Two cores have no init function in C: new BLBitSetBuilderCore() is ready to use, as C++'s BLBitSetBuilder (512-bit areas) is; bl_runtime_scope_begin() initialises a BLRuntimeScopeCore.
  • BLStrokeOptionsCore's fields are properties ($so->width = 4.0), since C sets them directly and Blend2D has no setters. dash_array must be an array of doubles.
  • Value structs (BLPoint, BLRect, BLMatrix2D, BLGlyphRun, the info structs, …) have one typed property per C field; a field not given, by position or by name, is C's zero (new BLApproximationOptions(flatten_tolerance: 0.2)). A struct Blend2D writes is a by-reference argument.
  • Lists stand for a pointer and count (BLPoint arrays, gradient stops, glyph ids); the count stays its own argument and may not exceed the list.
  • Bytes and text are strings. A size may not exceed the string; -1 means "up to the NUL", which every PHP string has. UTF-16/32 text is a string of code units in the CPU's byte order.
  • Pointer returns: bl_array_get_data() and bl_string_get_data() return the address as C does; copy: true returns a copy. bl_path_get_vertex_data, bl_path_get_command_data and bl_gradient_get_stops come back as copies.
  • bl_image_init_as_from_data() / bl_image_create_from_data() take a string (kept alive by the binding) or an int address (trusted: the caller keeps it valid). bl_pixel_converter_convert() takes an address on either side.
  • Writable pointers Blend2D hands out (*_make_mutable, *_modify_op) are integer addresses.
  • Borrowed memory (bl_image_init_as_from_data, bl_image_create_from_data, bl_array_assign_external_data, bl_font_data_create_from_data) is a string the binding keeps alive until Blend2D lets go of it. Blend2D draws into image strings in place; build them at run time (str_repeat()), not as literals.
  • bl_runtime_query_info assigns the info struct its type names; bl_file_read fills a new string of up to n bytes.

Callbacks

The path sinks of bl_path_stroke_to_sink, bl_font_get_glyph_outlines and bl_font_get_glyph_run_outlines, and bl_glyph_buffer_set_debug_sink, take a PHP callable, called on the calling thread. A sink's return value is its BLResult; an exception stops the walk and is rethrown. Worker threads never call PHP.

Errors

Blend2D reports failure through BL_ERROR_* values, which come back as ints. Arguments Blend2D would trust and crash on are refused before it runs: an uninitialised core or one of the wrong kind (Error, TypeError), and a short buffer, a count past its list, an enum out of range, an insert position past the end, an object array where a codec array or a double array is required, an op that would leave object slots for C code to construct, a glyph run with glyphs but no glyph data, an A8 image over your memory whose row stride is not a multiple of 4 (Blend2D's JIT writes past such an image), and a path with NaN or infinite coordinates handed to a fill or stroke (Blend2D's edge builder can loop forever on one; a close command's vertex, NaN by Blend2D's design, is not counted) (ValueError). A file outside open_basedir answers BL_ERROR_ACCESS_DENIED with PHP's warning, as fopen would.

Running the test suite

composer install
php -d memory_limit=512M vendor/bin/pest
php -d memory_limit=512M 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 and fonts are trusted input.

License

MIT for this extension. Blend2D is zlib, lib/blend2d/LICENSE.md; asmjit is zlib, lib/blend2d/3rdparty/asmjit/LICENSE.md.