PHPackages                             watsonhaw/lychee-worker - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. watsonhaw/lychee-worker

ActiveLibrary[HTTP & Networking](/categories/http)

watsonhaw/lychee-worker
=======================

Rust-powered high-performance runtime — prefork HTTP/WebSocket server with hot-reload

v0.1.0(1mo ago)00MITPHPPHP >=8.3,<8.4CI passing

Since Jul 16Pushed 1mo agoCompare

[ Source](https://github.com/watsonhaw5566/lychee-worker)[ Packagist](https://packagist.org/packages/watsonhaw/lychee-worker)[ RSS](/packages/watsonhaw-lychee-worker/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (9)Versions (4)Used By (0)

lychee-worker
=============

[](#lychee-worker)

基于 Rust (tokio + tokio-tungstenite) 重写的轻量级 PHP 运行时，同时提供 **ThinkPHP 8 插件** 封装，为 ThinkPHP 项目提供高性能的 HTTP/WebSocket 服务。

本项目包含两部分：

1. **Rust PHP 扩展**（`lychee_worker.so` / `lychee_worker.dylib`） — 向 PHP 导出 `lychee_worker_start` 等一整套原生函数。真正的 HTTP / WebSocket / 房间 / 广播 / 热更新 / 信号处理都在扩展里以原生 Rust 跑。
2. **ThinkPHP 8 插件**（`src/` 目录） — 符合 PSR-4，命名空间 `lychee\worker\`，通过 `composer.json` 的 `extra.think.services` 自动注册到 ThinkPHP 容器，提供 `php think worker` 命令行入口、`Manager` 管理器和 `Websocket` 门面类。

特性
--

[](#特性)

- **Prefork 多进程**：父进程 fork N 个子进程，每个子进程跑独立的 tokio 事件循环，避免 PHP ZTS 问题；主进程 + 子进程总数显示在控制台
- **原生 HTTP/1.1**：纯 Rust 手动解析（method / path / headers / body），零依赖 FPM/nginx
- **原生 WebSocket**：tokio-tungstenite，支持连接建立/消息/关闭回调，进程内房间广播
- **单点发送与广播**：`lychee_worker_ws_send` / `lychee_worker_ws_emit` / `lychee_worker_ws_broadcast` / `lychee_worker_ws_broadcast_room`
- **房间管理**：`lychee_worker_join_room` / `lychee_worker_leave_room` / `lychee_worker_conn_rooms` / `lychee_worker_room_count`（进程内，暂无跨进程 IPC）
- **队列消费**（可选）：独立 PHP 子进程 (`php think worker:queue`) 轮询消费已注册队列任务
- **热更新**：mtime 轮询，检测到 app/config/route 目录文件变化后自动重启所有子进程；也可通过 `lychee_worker_trigger_reload()` 手动触发
- **优雅关闭**：捕获 SIGINT/SIGTERM，关闭所有子进程后退出
- **运行时统计与内存**：`lychee_worker_stats()` 返回 connections / requests / rooms / ws / memory（当前进程物理内存 RSS，单位 MB）。
- **控制台输出**：启动表格显示协议、监听地址、进程数、状态（类似 Workerman 风格）

运行环境要求
------

[](#运行环境要求)

组件最低版本说明PHP8.3需要 `php-config`、`phpize` 等开发工具（通常由 `php-dev` / `php-devel` 包提供）。仅支持 PHP 8.3；ext-php-rs 在构建时通过 `php-config` 探测版本Rust1.70+推荐通过 rustup 安装操作系统Linux / macOS当前仅在 Linux/macOS 验证构建与运行ThinkPHP 8 命令一览
---------------

[](#thinkphp-8-命令一览)

安装插件后，`php think` 会多出以下命令：

命令说明`php think worker`**生产模式**：启动 HTTP/WebSocket 服务器，文件 watcher 关闭（无热更新）`php think worker:dev`**开发模式**：同 `worker`，但启用文件监控与热更新（`app/config/route/*.php` 变化时自动重启子进程）`php think worker:queue`**队列消费进程**（由 `enable_queue=true` 时 Rust 侧自动 fork，一般不需手动调用）`php think worker:child`**HTTP 子进程入口**（由 Rust 侧 fork，一般不需手动调用）`php think worker:status`查询运行时统计：connections / ws / requests / rooms / **memory**（MB）。直接执行，无需在 worker 进程内调用`worker` 与 `worker:dev` 均支持 `--host`、`--port`、`--workers` 参数覆盖配置文件：

```
php think worker --host=127.0.0.1 --port=9090 --workers=4
```

安装
--

[](#安装)

本项目同时提供 `pie.json`（声明 `type: php-ext`），可被 [PIE](https://php.github.io/pie/)（PHP Installer for Extensions）识别为 PHP 扩展并构建；`composer.json` 的 `type` 为标准 `library`，确保 ThinkPHP 项目的 `extra.think` 自动发现与 Composer autoload 正常工作。

### 前置条件

[](#前置条件)

- PHP 8.3（含 `php-config`）
- 若使用**免构建**安装（推荐）：安装 [PIE](https://php.github.io/pie/)（PHP Installer for Extensions）即可，**无需 Rust 工具链**
- 若要从源码构建：Rust 工具链（`rustup install stable && rustup default stable`）

### 一键安装（PIE · 免构建，推荐）

[](#一键安装pie--免构建推荐)

`pie.json` 已声明 `download-url-method: [pre-packaged-binary, composer-default]`，PIE 会优先从 GitHub Release 下载当前平台的预编译 `.so`/`.dylib`，**不触发 cargo build**，也就不依赖 Rust 工具链：

```
pie install watsonhaw/lychee-worker
```

若当前平台没有预编译产物，PIE 会自动回退到 `composer-default`（下载源码 → configure → make → make install），此时才需要 Rust 工具链。

### 一键安装（PIE · 源码构建）

[](#一键安装pie--源码构建)

当 PIE 回退到源码构建时，它会自动：

1. 下载源码
2. 执行 `./configure`（检测工具链并生成 Makefile）
3. 执行 `make`（底层为 `cargo build --release`）
4. 执行 `make install`（底层为 `bash scripts/install.sh`，拷贝 `.so` 到扩展目录并写入 `php.ini`）

### 在 ThinkPHP 8 项目中安装（Composer 路径）

[](#在-thinkphp-8-项目中安装composer-路径)

```
# 进入你的 ThinkPHP 8 项目根目录
cd /path/to/your-thinkphp-project

# 1. 允许 dev 稳定性并拉取包
composer config minimum-stability dev
composer config prefer-stable true
composer require watsonhaw/lychee-worker

# 2. 编译并安装 Rust 扩展
bash vendor/watsonhaw/lychee-worker/scripts/install.sh

# 3. 验证扩展是否已加载
php -m | grep lychee_worker

# 4. 启动服务
php think worker
```

### 分步编译

[](#分步编译)

如果不想用 PIE，也可以手动分步完成构建。以 ThinkPHP 8 项目为例，`composer require` 后进入包目录执行：

```
cd vendor/watsonhaw/lychee-worker

# 步骤 1：编译 Rust 扩展（release 模式，产物在 target/release/）
cargo build --release

# 步骤 2：将 .so / .dylib 拷贝到 PHP 扩展目录，并写入 php.ini
bash scripts/install.sh

# 步骤 3：验证扩展是否已加载
php -m | grep lychee_worker
```

`scripts/install.sh` 会自动：

1. 检测当前操作系统（Linux 输出 `.so`，macOS 输出 `.dylib`）
2. 若 `target/release/liblychee_worker.*` 不存在，自动执行 `cargo build --release`
3. 把编译产物复制到 `php-config --extension-dir` 指向的目录
4. 在 macOS 上执行 `codesign --force --deep -s -` 以通过 SIP
5. 自动在已加载的 `php.ini`（或 `conf.d/99-lychee_worker.ini`）追加 `extension=/absolute/path/to/lychee_worker.so`
6. 用 `php -m` 验证扩展是否被成功加载

`scripts/install.sh` 支持以下参数：

```
bash scripts/install.sh                                # 编译 + 复制 + 写入 php.ini（默认）
bash scripts/install.sh --no-ini                       # 只复制扩展文件，不修改 php.ini
bash scripts/install.sh --ini=/path/to/custom/php.ini  # 指定自定义 php.ini 路径
bash scripts/install.sh --from-github-release=0.1.0    # 从 GitHub Release 下载预编译二进制，
                                                       # 不执行 cargo build（无需 Rust 工具链）
bash scripts/install.sh --from-github-release=latest   # 使用最新 release 的预编译产物
```

> 使用 `--from-github-release` 时，脚本会根据当前 OS / 架构 / libc / PHP 版本生成 PIE 预编译包名 `php_lychee_worker-_php8.3----release-nts.zip`，并从 GitHub Release 的浏览器下载链接拉取该 ZIP；对历史版本会回退到原始 `liblychee_worker-.so` 命名。下载后如果是 ZIP 会自动解包，然后再执行拷贝和 php.ini 注入。

### 直接下载预编译产物（无 PIE / 无 install.sh）

[](#直接下载预编译产物无-pie--无-installsh)

Release 页会同时挂出符合 PIE 命名规范的 ZIP 包，以及 `liblychee_worker--.so`原始文件。只需：

```
wget https://github.com/watsonhaw5566/lychee-worker/releases/latest/download/liblychee_worker-$(uname)-x86_64.so
cp liblychee_worker-*.so "$(php-config --extension-dir)/lychee_worker.so"
echo 'extension=lychee_worker.so' >> "$(php --ini | awk -F': ' '/Loaded Configuration File/ {print $2; exit}')"
php -m | grep lychee_worker
```

### 在包源码目录中构建（开发/测试场景）

[](#在包源码目录中构建开发测试场景)

如果是直接克隆 `lychee-worker` 源码进行开发，无需进入 `vendor/`，在项目根目录即可：

```
cd /path/to/lychee-worker

# 方法 A：Composer 脚本别名
composer run-script install-ext

# 方法 B：直接执行脚本
bash scripts/install.sh

# 方法 C：完全手动
cargo build --release
cp target/release/liblychee_worker.dylib "$(php-config --extension-dir)/lychee_worker.dylib"
echo "extension=$(php-config --extension-dir)/lychee_worker.dylib" >> "$(php --ini | awk -F': ' '/Loaded Configuration File/ {print $2; exit}')"
php -m | grep lychee_worker
```

### 验证

[](#验证)

```
php -m | grep lychee_worker
```

若上面的命令没有任何输出，说明扩展未被加载。请检查：

1. `php-config --extension-dir` 目录下是否存在 `lychee_worker.so`（Linux）或 `lychee_worker.dylib`（macOS）
2. 当前执行的 `php` 所使用的 `php.ini`（通过 `php --ini` 查看）是否包含 `extension=.../lychee_worker.*` 这一行
3. macOS 下如果提示签名相关错误，可重新执行 `bash scripts/install.sh`，脚本会自动 `codesign`

> **说明**：包内的 ThinkPHP 插件类（`src/` 下的 PSR-4 代码）由 Composer 正常 autoload，ThinkPHP 项目安装扩展后即可使用 `php think worker` 命令启动服务。

升级与卸载
-----

[](#升级与卸载)

```
# 升级
composer update watsonhaw/lychee-worker
bash vendor/watsonhaw/lychee-worker/scripts/install.sh

# 卸载
php -r "echo ini_get('extension_dir') . PHP_EOL;"
# 删除上面目录里的 lychee_worker.so / lychee_worker.dylib
# 并从 php.ini 移除 extension=lychee_worker 这行
composer remove watsonhaw/lychee-worker
```

最小使用示例
------

[](#最小使用示例)

把下面内容保存为 `server.php`，然后 `php server.php`：

```