wen130 / framework

4.0.85 2026-10-29 01:19 UTC

Requires

• php: >=8.1
• ext-json: *
• ext-mbstring: *
• ext-openssl: *
• ext-pdo: *
• guzzlehttp/guzzle: ^7.0 || ^8.0
• nikic/fast-route: ^1.3
• nyholm/psr7: ^1.8
• nyholm/psr7-server: ^1.1
• psr/container: ^2.0
• psr/event-dispatcher: ^1.0
• psr/http-message: ^2.0
• psr/http-server-middleware: ^1.0
• psr/log: ^3.0
• psr/simple-cache: ^3.0
• workerman/workerman: ^5.1

Suggests

• ext-apcu: nosql\ApcuCache
• ext-curl: HttpClient 的 Curl 系列 handler、RestClient
• ext-fileinfo: MIME 类型探测
• ext-iconv: 编码转换（Text / UploadFile）
• ext-pcntl: Workerman CLI 进程管理
• ext-posix: Workerman CLI 进程管理
• ext-redis: nosql 下 RedisConnection / Kvrocks* 全家桶
• ext-sockets: 原生 socket 相关组件
• ext-swoole: Swoole 协程、连接池、swoole HTTP 入口
• ext-zip: util 下的 zip 处理

MIT

• huangshaowen

Published on Packagist.org on 2026-10-29 01:45 UTC

README

轻量级 PHP 框架，支持 Web（PHP-FPM） / Workerman / Workerman 协程 / Swoole / CLI 五种运行模式。生产环境已验证，非通用框架。

版本 4.0.81（以 packages/framework/composer.json 为准） | PHP >= 8.1 | Workerman 5.x / Swoole >= 6.0

特性

• 环境自适应：一套代码五模式无缝切换，协程混合部署（按端口独立开关）
• PSR 标准化：PSR-7 请求/响应、PSR-11 容器、PSR-14 事件分发、PSR-15 中间件、PSR-16 缓存接口
• 路由系统：FastRoute 正则/规则路由 + 路由分组（前缀 + 中间件）
• 参数自动注入：控制器方法参数自动从协程隔离的 Request 匹配（路由变量 + GET/POST），不读共享超全局 $_GET/$_POST
• 协程安全：Request/Session/Cookie/View/Dispatcher/DB/NoSQL 按协程隔离（Swoole 原生 Context / Workerman Fiber）
• 异常 HTTP 状态码：throw new Exception('msg', 402) → 自动 HTTP 402
• SSE 流式响应：chunkedStart/sendChunk/chunkedEnd（Web / Workerman / Swoole 全支持）
• Cookie 全环境：Cookie::set() 自动适配 Web header() / Workerman / Swoole Set-Cookie
• 开发热重载：FileMonitor 文件变化自动重启（Workerman + Swoole 双实现）
• 内存泄漏防护：max_request 自动重启 worker，Workerman 额外支持 memory_limit + gc_interval

数据库 framework\db

• 多驱动连接：按运行环境自动选型 pdo（FPM）/ swoole（每协程独立 PDO + 信号量限流）/ swoole_pool（Swoole PDOPool 连接池，CLI 批量任务默认）/ workerman（连接池 + 协程隔离）
• 连接健康：ping() 心跳检测 + checkAlive() 懒检测 + reconnect() 自动重建（ping_interval 默认 300s 可配置，连续重连超限抛异常）
• API 对齐 ThinkORM 4：db::table/name/connect/query/transaction + 链式 query 构建器（whereIn/whereBetween/whereFindInSet/join/chunk/insertDuplicate/...），零魔术方法、IDE 友好

缓存与 NoSQL framework\nosql

• Kvrocks / Redis 协程安全连接：KvrocksConnection / RedisConnection，三模式自适应（Swoole 官方 RedisPool / Workerman Fiber Pool / 进程级单例），禁止裸 new \Redis()
• Kvrocks 业务组件族：通用缓存、分布式锁（KvrocksLock）、限流（KvrocksRateLimiter：固定/滑动窗口/令牌桶）、队列（轻量 KvrocksQueue + 可靠 at-least-once KvrocksTaskQueue）、布隆过滤器、HyperLogLog、排行榜、Stream 消息流、版本缓存（CAS）、位图
• PSR-16 缓存：SimpleCache（Kvrocks 后端）、ApcuCache（进程内共享内存）

任务队列 framework\mq\lmstfy

• 现役任务队列组件，支持实时 + 长延时任务，基于 Kvrocks 连接层（详见 lmstfy 队列）

HTTP 客户端 framework\HttpClient

• 一套调用、三种传输：在 Guzzle 7 的 leaf handler 上扩展，按运行环境自动分派 Swoole 原生协程 / Workerman 异步 / curl 阻塞，调用方不写引擎判定（判定只在 CoroutineHandler 里实现一次，Swoole 下不会误用会静默返 null 的 Workerman\Http\Client）
• 入口：ClientFactory::create(array $config) 返回标准 \GuzzleHttp\Client（全套选项与中间件可用）；pool 连接池 / stream 流式均为显式 opt-in（默认关），不支持的能力一律抛异常而非静默降级
• 详见 HTTP 客户端设计

Swoole 6.0 适配

• Swoole 6.x 已移除 \Swoole\Coroutine\Redis/MySQL/PostgreSQL 内置协程客户端及 SWOOLE_HOOK_PDO/REDIS 常量；框架统一走「原生客户端 + SWOOLE_HOOK_ALL」范式，连接层（DB / RedisConnection / KvrocksConnection）全部适配，引用 SWOOLE_HOOK_* 前以 defined() 保护。

组件总览

模块	命名空间	说明
core	framework\core	App 引导，Request/Response/Cookie/Session/View/Dispatcher/Action/Config/Log，协程上下文，五模式 Processor（web/workerman/swoole/cli）
router	framework\router	FastRoute 封装，路由分组 + 中间件
container	framework\container	PSR-11 容器
psr7	framework\psr7	PSR-7 请求工厂
event	framework\event	PSR-14 事件分发（EventDispatcher / ListenerProvider / AbstractEvent）
HttpClient	framework\HttpClient	协程化 HTTP 传输层：Guzzle leaf handler + 引擎自动分派（Swoole / Workerman / curl），连接池与流式可选
db	framework\db	多驱动数据库连接、连接池、事务、心跳保活
nosql	framework\nosql	Kvrocks / Redis 连接层 + 业务组件族、PSR-16 缓存
mq	framework\mq	lmstfy 任务队列（实时 + 长延时）
session	framework\session	Redis 会话驱动
serializer	framework\serializer	Json / igbinary / msgpack / php / Text 序列化器（phpSerializer 解码默认不实例化类，需对象时显式传 allowed_classes 白名单）
crypto	framework\crypto	AES、RSA
util	framework\util	Text / Time / Ulid / UploadFile / Validate / Net
tpl	framework\tpl	跳转 / 404 / 错误页模板

安装

composer require wen130/framework

快速开始

// 入口文件 index.php
define('ROOT_PATH', str_replace('\\', '/', __DIR__) . '/');
require ROOT_PATH . 'vendor/autoload.php';
\framework\core\App::getInstance()->run();

# Web (PHP-FPM)
http://www.dev.com

# Workerman
php -c php.ini workerman/start_web_api.php start -d

# 🆕 Swoole
php -c php.ini workerman/start_swoole.php        # 前台（开发）
php -c php.ini workerman/start_swoole.php -d     # 后台（生产）
php -c php.ini workerman/start_swoole.php -d -p 8096 -w 1   # 指定端口 + 1进程（AI等大内存场景）
kill -USR1 $(cat cache/swoole{port}.pid)                # 热重载

控制器示例

namespace www\action;
use framework\core\Action;

class index extends Action {
    public function index() {
        return ['ret' => 200, 'data' => null, 'msg' => 'ok'];
    }

    // 参数自动注入
    public function search(string $keyword, int $page = 1) {
        return $this->logic->search($keyword, $page);
    }

    // HTTP 状态码异常
    public function check() {
        if (!loggedIn()) throw new \Exception('请登录', 401);
    }
}

运行模式

模式	命令	协程	适用
Web (FPM)	Nginx → index.php	—	传统 Web
Workerman	workerman/start_web_api.php	—	同步 API（协程由 data/workerman.php 的 event_loop 控制）
Workerman 协程	workerman/start_web_api.php	Fiber / Swoole 驱动	AI / 长连接
🆕 Swoole	workerman/start_swoole.php	原生	替代 Workerman 协程
CLI	php index.php /api/task/<api>/<controller>/<action>	—	定时任务 / 组件自测

文档

• 技能速查 — 一页式硬约束与 API 速查（写码前先看）
• 设计文档 — 架构、模块设计、运行模式、异常处理
• 开发文档 — 快速开始、路由、数据库、中间件、SSE、Swoole
• 最佳实践 — 分层、缓存、安全、部署、Swoole 运维
• DB 设计 — framework\db 多驱动连接、连接池、事务、心跳保活
• Kvrocks 指南 — framework\nosql 全部 Kvrocks 组件使用说明
• 工具类 — Text / Time / Ulid / UploadFile / Validate / Net
• lmstfy 队列 — 现役任务队列组件（实时 + 长延时）设计文档
• 事件系统 — PSR-14 事件分发（EventDispatcher / ListenerProvider）
• HTTP 客户端设计 — framework\HttpClient 协程化 HTTP 传输层（Guzzle leaf handler 方案；阶段 1/2/3/6/7/8 已落地并实测，OpenSearch 8 个入口与 RestClient 已迁完）