# framework

**Repository Path**: wen130/framework

## Basic Information

- **Project Name**: framework
- **Description**: 简洁的自用的php框架
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2020-07-19
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Framework

轻量级 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 队列](doc/lmstfy.md)）

### 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 客户端设计](doc/http_client.md)

### 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 / 错误页模板 |

## 安装

```bash
composer require wen130/framework
```

## 快速开始

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

```bash
# 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)                # 热重载

```

## 控制器示例

```php
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>` | — | 定时任务 / 组件自测 |

## 文档

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