php-wasm

纯 PHP 环境下以编程方式构建 WebAssembly (Wasm) 二进制模块的库，底层通过 FFI 调用跨平台 C 编译库实现高性能指令编码。

✨ 核心特性

• 纯 PHP 生成 Wasm — 无需外部工具链，直接在 PHP 中编写并编译 .wasm 二进制模块

• 完整 Wasm 指令集 — 覆盖常量、局部/全局变量、算术、位运算、比较、类型转换、控制流（block/loop/if-else/br）、内存操作、引用操作

• 链式调用 API — $fn->getLocal(0)->getLocal(1)->add(NumType::I32) 风格流畅编程

• Debug 模式 — 生成带 DWARF 调试信息（参数名、类型名）的 Wasm 模块

• 函数导入/导出 — 支持 import 外部函数/全局变量，export 内部函数/内存

• 全局变量 & 内存管理 — 可变的全局变量、线性内存配置、数据段（主动/被动）

• 跨平台支持 — Windows/Linux/macOS，x86_64/arm64 架构

📋 环境要求

🚀 安装

composer  require  kingbes/wasm

⚡ 快速开始

<?php
require  "vendor/autoload.php";
use Kingbes\Wasm\Module;
use Kingbes\Wasm\ValType;
use Kingbes\Wasm\NumType;

// 1. 创建模块
$mod = new  Module();
// 2. 创建函数
$fn = $mod->newFn([
 "name" => "add",                          // 函数名
 "params" => [ValType::I32, ValType::I32], // 参数类型
 "results" => [ValType::I32], // 返回值类型
]);

// 3. 编写函数体（链式调用）
$fn->getLocal(0)            // local.get 0 — 压入第一个参数
   ->getLocal(1)            // local.get 1 — 压入第二个参数
   ->add(NumType::I32); // i32.add

// 4. 提交并导出
$mod->commit($fn);

// 5. 编译输出
$mod->compile("./add.wasm");

等价 WAT 文本：

(module
  (func (export "add") (param i32 i32) (result i32)
    local.get 0
    local.get 1
    i32.add
  )
)

📦 核心类

Module — 模块管理

Func — 函数体指令

类型枚举

ConstExpression — 常量表达式

new  ConstExpression(100); // i32.const
new  ConstExpression(3.14);                // f32.const
new  ConstExpression(ValType::I32);        // i32.const 0
new  ConstExpression(RefType::FuncRef);    // ref.null func

FunType — 函数类型（Debug 模式）

new  FunType(
    [ValType::I32, ValType::I64],  // 参数类型
    [ValType::I32],                // 返回类型
 "add_type"  // 类型名
);

📖 使用示例

条件分支 (if-else)

$mod = new  Module();
$fn = $mod->newFn([
 "name" => "is_positive",
 "params" => [ValType::I32],
 "results" => [ValType::I32],
]);
$label = $fn->if_([], [ValType::I32]);
$fn->const(1); // then: 返回 1
$fn->else_($label);
$fn->const(0); // else: 返回 0
$fn->end($label);
$mod->commit($fn);
$mod->compile("./is_positive.wasm");

循环 (loop)

// sum(n) = 1 + 2 + ... + n
$fn = $mod->newFn([
 "name" => "sum",
 "params" => [ValType::I32],
 "results" => [ValType::I32],
]);
$i = $fn->newLocal(ValType::I32);
$acc = $fn->newLocal(ValType::I32);
$fn->getLocal(0)->setLocal($i);
$fn->const(0)->setLocal($acc);
$loop = $fn->loop([], []);
$fn->getLocal($i)->const(0)->gt(NumType::I32, true);
$fn->brIf(1);  // i <= 0 则跳出
$fn->getLocal($acc)->getLocal($i)->add(NumType::I32)->setLocal($acc);
$fn->getLocal($i)->const(1)->sub(NumType::I32)->setLocal($i);
$fn->br(0);    // 继续循环
$fn->end($loop);
$fn->getLocal($acc);
$mod->commit($fn);
$mod->compile("./sum.wasm");

内存操作

$mod = new  Module();
$mod->assignMemory("mem", true, 1, 1);  // 1 页（64KB）
// store_value(addr, val)
$fn = $mod->newFn([
 "name" => "store_value",
 "params" => [ValType::I32, ValType::I32],
 "results" => [],
]);
$fn->getLocal(0)->getLocal(1)->store(NumType::I32, 2, 0);
$mod->commit($fn);
// load_value(addr) -> i32
$fn2 = $mod->newFn([
 "name" => "load_value",
 "params" => [ValType::I32],
 "results" => [ValType::I32],
]);
$fn2->getLocal(0)->load(NumType::I32, 2, 0);
$mod->commit($fn2);
$mod->compile("./memory.wasm");

函数导入与调用

$mod = new  Module();
// 导入外部函数 print_num(i32) -> ()
$mod->impFn("env", "print_num", [
 "params" => [ValType::I32],
 "results" => [],
]);

// 创建函数调用导入
$fn = $mod->newFn([
 "name" => "do_print",
 "params" => [ValType::I32],
 "results" => [],
]);

$fn->getLocal(0)->callImport("env", "print_num");
$mod->commit($fn);
$mod->compile("./import.wasm");

Debug 模式

$mod = new  Module();
$mod->enableDebug("my_module");
$fn = $mod->newFn([
 "name" => "add",
 "params" => [ValType::I32, ValType::I32],
 "results" => [ValType::I32],
 "param_names" => ["a", "b"], // Debug 必填
 "type_name" => "add_type", // Debug 必填
], true);
$fn->getLocal(0)->getLocal(1)->add(NumType::I32);
$mod->commit($fn);
$mod->compile("./add_debug.wasm");

全局变量

use Kingbes\Wasm\ConstExpression;
$mod = new  Module();
$counter = $mod->newGlobal("counter", true, ValType::I32, true, new  ConstExpression(0));
$fn = $mod->newFn([
 "name" => "increment",
 "params" => [],
 "results" => [],
]);
$fn->getGlobal($counter)->const(1)->add(NumType::I32)->setGlobal($counter);
$mod->commit($fn);
$mod->compile("./counter.wasm");

数据段

$mod = new  Module();
$mod->assignMemory("mem", true, 1, 1);
$mod->newDataSegment("hello", 0, "Hello, World!");
$fn = $mod->newFn([
 "name" => "get_byte",
 "params" => [ValType::I32],
 "results" => [ValType::I32],
]);
$fn->getLocal(0)->load8(NumType::I32, false, 0, 0);  // i32.load8_u
$mod->commit($fn);
$mod->compile("./data.wasm");

📚 详细文档

📄 License

MIT

本作品采用《CC 协议》，转载必须注明作者和本文链接