compiler/examples/wasm-hello/README.md

TypePHP WASI Browser Lab

这是一个由 project.yml 构建的完整 TypePHP/WASI 0.2 浏览器应用。PHP 代码编译成一个自包含的 Component，Jco 将同一个 Component 转译为浏览器 ESM，页面通过 module Worker 加载它。

Demo 展示以下已支持能力：

• 命令行参数、环境变量与标准输入/输出
• WASI wall clock 和 PHP time() / date()
• 安全随机数 random_int() / random_bytes()
• 内存文件系统，以及可选的 OPFS 快照持久化
• 通过同步 file_get_contents() 发起 HTTP/HTTPS GET；浏览器等待期间由 JSPI 挂起 Wasm 调用栈
• PHP 8.5 runtime 信息
• 由 get_loaded_extensions() 动态读取的 PHP/WASI 内置扩展列表
• TypePHP 语言级 BigInt、Decimal、BigFloat 高精度计算

原始 socket、进程、shell、信号、Fiber 和 Generator 明确不支持。

浏览器构建要求支持 WebAssembly.Suspending 和 WebAssembly.promising 的 JSPI 实现。HTTP 请求仍受浏览器 CORS、CSP 和 Mixed Content 策略约束。 file_get_contents() 当前支持 GET、http.timeout 和 http.ignore_errors；不提供 Curl API，也不会退化为忙等待。

构建

先确保 WASI SDK 和 Wasmtime 已加入 PATH，然后在本目录执行：

npm ci
npm run wasm

等价的仓库根目录命令是：

php bin/tpc.php examples/wasm-hello/project.yml

project.yml 控制全部项目路径：

• sources: src：TypePHP 源码
• build-dir: build：生成的 C++ 与目标文件
• output: component/wasm-hello.wasm：WASI 0.2 Component
• wasm: browser：显式生成浏览器模块；简单项目使用 wasm: component 只生成 Component
• 未配置 target-platform 时，WASM 项目默认使用 wasm32-wasip2
• wasm-browser-dir: generated：Jco 浏览器模块

Jco 是本项目的开发依赖。先执行 npm ci，之后通过 npm run wasm 构建时，npm 会自动把本地 node_modules/.bin/jco 加入 PATH。

若只需要供 Wasmtime 使用的 Component，可以绕过 Jco：

php ../../bin/tpc.php project.yml --wasm=component

浏览器运行

npm run dev

打开终端显示的本地地址。可以修改参数、环境变量和 stdin 后重复运行；勾选 OPFS 后，PHP 写入虚拟文件系统的运行次数会跨页面刷新保存。

生产构建：

npm run build

src/ 是 TypePHP 应用，typephp-worker.mjs 是浏览器 WASI host，main.js 和 style.css 负责交互界面。build/、component/、dist/、generated/ 均为可重新生成的输出。

WASI 运行库、PHPX 和生成的 C++ 均使用 -O2 编译。最终链接会移除调试与符号段，以减少浏览器下载、解析和编译 Wasm 的开销；构建过程不会自动调用系统中的 wasm-opt，避免旧版 Binaryen 与 WASI SDK 生成的 Wasm 异常指令不兼容。