extism / extism
Make your software programmable. Run WebAssembly extensions in your app using the first off-the-shelf, universal plug-in system.
Requires
- php: ^7.4 || ^8
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.59
- phpunit/phpunit: ^9
- squizlabs/php_codesniffer: ^3.10
This package is auto-updated.
Last update: 2024-10-01 00:09:07 UTC
README
This repo houses the PHP SDK for integrating with the Extism runtime. Install this library into your host PHP applications to run Extism plugins.
Installation
Install the Extism Runtime Dependency
For this library, you first need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:
sudo extism lib install latest #=> Fetching https://github.com/extism/extism/releases/download/v0.5.2/libextism-aarch64-apple-darwin-v0.5.2.tar.gz #=> Copying libextism.dylib to /usr/local/lib/libextism.dylib #=> Copying extism.h to /usr/local/include/extism.h
Note: This library has breaking changes and targets 1.0 of the runtime. For the time being, install the runtime from our nightly development builds on git:
sudo extism lib install --version git
.
Install the Package
Install via Packagist:
composer require extism/extism
Note: For the time being you may need to add a minimum-stability of "dev" to your composer.json
{ "minimum-stability": "dev", }
Getting Started
This guide should walk you through some of the concepts in Extism and this PHP library.
First you should add a using statement for Extism:
use Extism\Plugin; use Extism\Manifest; use Extism\Manifest\UrlWasmSource;
Creating A Plug-in
The primary concept in Extism is the plug-in. You can think of a plug-in as a code module stored in a .wasm
file.
Since you may not have an Extism plug-in on hand to test, let's load a demo plug-in from the web:
$wasm = new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"); $manifest = new Manifest($wasm); $plugin = new Plugin($manifest, true);
Note: The schema for this manifest can be found here: https://extism.org/docs/concepts/manifest/
Calling A Plug-in's Exports
This plug-in was written in Rust and it does one thing, it counts vowels in a string. As such, it exposes one "export" function: count_vowels
. We can call exports using Plugin.call
:
$output = $plugin->call("count_vowels", "Hello, World!"); // => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
All exports have a simple interface of optional bytes in, and optional bytes out. This plug-in happens to take a string and return a JSON encoded string with a report of results.
Plug-in State
Plug-ins may be stateful or stateless. Plug-ins can maintain state b/w calls by the use of variables. Our count vowels plug-in remembers the total number of vowels it's ever counted in the "total" key in the result. You can see this by making subsequent calls to the export:
$output = $plugin->call("count_vowels", "Hello, World!"); // => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"} $output = $plugin->call("count_vowels", "Hello, World!"); // => {"count": 3, "total": 9, "vowels": "aeiouAEIOU"}
These variables will persist until this plug-in is freed or you initialize a new one.
Configuration
Plug-ins may optionally take a configuration object. This is a static way to configure the plug-in. Our count-vowels plugin takes an optional configuration to change out which characters are considered vowels. Example:
$wasm = new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"); $manifest = new Manifest($wasm); $plugin = new Plugin($manifest, true); $output = $plugin->call("count_vowels", "Yellow, World!"); // => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"} $manifest = new Manifest($wasm); $manifest->config->vowels = "aeiouyAEIOUY"; $plugin = new Plugin($manifest, true); $output = $plugin->call("count_vowels", "Yellow, World!"); // => {"count": 4, "total": 4, "vowels": "aeiouAEIOUY"}
Host Functions
Note
Host Functions support is experimental. Due to usage of callbacks with FFI, It may leak memory.
Let's extend our count-vowels example a little bit: Instead of storing the total
in an ephemeral plug-in var, let's store it in a persistent key-value store!
Wasm can't use our KV store on it's own. This is where Host Functions
come in.
Host functions allow us to grant new capabilities to our plug-ins from our application. They are simply some PHP functions you write which can be passed down and invoked from any language inside the plug-in.
Let's load the manifest like usual but load up this count_vowels_kvstore
plug-in:
$manifest = new Manifest(new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels_kvstore.wasm"));
Note: The source code for this is here and is written in rust, but it could be written in any of our PDK languages.
Unlike our previous plug-in, this plug-in expects you to provide host functions that satisfy our import interface for a KV store.
We want to expose two functions to our plugin, void kv_write(key string, value byte[])
which writes a bytes value to a key and byte[] kv_read(key string)
which reads the bytes at the given key
.
// pretend this is Redis or something :) $kvstore = []; $kvRead = new HostFunction("kv_read", [ExtismValType::I64], [ExtismValType::I64], function (string $key) use (&$kvstore) { $value = $kvstore[$key] ?? "\0\0\0\0"; echo "Read " . bytesToInt($value) . " from key=$key" . PHP_EOL; return $value; }); $kvWrite = new HostFunction("kv_write", [ExtismValType::I64, ExtismValType::I64], [], function (string $key, string $value) use (&$kvstore) { echo "Writing value=" . bytesToInt($value) . " from key=$key" . PHP_EOL; $kvstore[$key] = $value; }); function bytesToInt(string $bytes): int { $result = unpack("L", $bytes); return $result[1]; }
Note: The plugin provides memory pointers, which the SDK automatically converts into a
string
. Similarly, when a host function returns astring
, the SDK allocates it in the plugin memory and provides a pointer back to the plugin. For manual memory management, requestCurrentPlugin
as the first parameter of the host function. For example:$kvRead = new HostFunction("kv_read", [ExtismValType::I64], [ExtismValType::I64], function (CurrentPlugin $p, int $keyPtr) use ($kvstore) { $key = $p->read_block($keyPtr); $value = $kvstore[$key] ?? "\0\0\0\0"; return $p->write_block($value); });
We need to pass these imports to the plug-in to create them. All imports of a plug-in must be satisfied for it to be initialized:
$plugin = new Plugin($manifest, true, [$kvRead, $kvWrite]); $output = $plugin->call("count_vowels", "Hello World!"); echo($output . PHP_EOL); // => Read 0 from key=count-vowels" // => Writing value=3 from key=count-vowels" // => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"} $output = $plugin->call("count_vowels", "Hello World!"); echo($output . PHP_EOL); // => Read 3 from key=count-vowels" // => Writing value=6 from key=count-vowels" // => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}
For host function callbacks, these are the valid parameter types:
CurrentPlugin
: Only if its the first parameter. Allows you to manually manage memory. Optional.string
: If the parameter represents a memory offset (ani64
), then the SDK can automatically load the buffer into astring
for you.int
: Fori32
andi64
parameters.float
: Forf32
andf64
parameters.
Valid return types:
void
int
: Fori32
andi64
parameters.float
: Forf32
andf64
parameters.string
: the content of the string will be allocated in the wasm plugin memory and the offset (i64
) will be returned.