webman

webman 框架开发

webman 是一个基于 workerman 构建的高性能、长驻内存 PHP 框架。与 PHP-FPM（每个请求都要启动应用，响应后再销毁）不同，正确编写 webman 代码的前提是理解常驻进程模型。

核心心智模型：常驻内存

启动后，worker 会常驻内存并处理数千个请求。由此得出以下硬性规则：

1. 切勿使用 exit / die：它们会杀死整个 worker，并断开该进程上的所有连接。
2. 静态属性 / 全局变量会跨请求保留：前一个请求写入的数据可能会“泄漏”到下一个请求中。请将请求作用域的数据保存在局部变量、$request 属性中，或在协程下使用 support\Context。
3. 单例会在请求之间共享：不要在单例中存储请求状态；只增不减的数组属性会造成内存泄漏。
4. 代码更改需要重新加载或重启（php start.php reload）。在调试模式下，可使用 status / connections 排查问题。
5. 默认情况下，每个请求都会创建新的控制器（config/app.php 中的 controller_reuse => false）。如果启用了复用，控制器属性也会跨请求保留。

项目布局

├── app/                  # Application code
│   ├── controller/       # Controllers (optional; MVC or DDD as you prefer)
│   ├── model/            # Models
│   ├── middleware/       # Middleware
│   └── functions.php     # Custom helpers
├── config/               # All configuration
│   ├── route.php         # Routes
│   ├── process.php       # Process definitions (HTTP, custom, timers)
│   ├── middleware.php    # Middleware registration
│   ├── database.php      # Database (illuminate/database)
│   ├── redis.php         # Redis
│   └── plugin/           # Plugin config
├── plugin/               # Application plugins
├── public/               # Static assets (only web-accessible directory)
├── process/              # Custom process classes
├── support/              # Framework bridge code
└── start.php             # Entry point

常用命令

composer create-project workerman/webman   # create project

# Linux / macOS
php start.php start        # foreground (debug)
php start.php start -d     # daemon (production)
php start.php reload       # graceful reload (code updates, keep connections)
php start.php restart -d   # full restart (required after process.php, Timer, or resident data changes)
php start.php stop
php start.php status       # process memory, request counts
php start.php connections  # connection info

# Windows (no daemon / reload)
php windows.php

reload 与 restart 的区别：reload 只会重新加载应用代码（app/ 和大部分 config/）。对 config/process.php 的更改，或在 onWorkerStart 中已创建的定时器 / 连接，不会重新加载——请使用 restart。

编码约定

• PHP >= 8.0（webman v2 要求 8.1+）；始终使用 declare(strict_types=1)。
• 控制器方法签名：public function action(Request $request): Response，其中 Request 为 support\Request。
• 使用辅助函数（response()、json()、view()、redirect()、…）返回 Webman\Http\Response。不要使用 echo。
• 优先使用 illuminate/database（Db::table() / 继承 support\Model 的 Eloquent 模型）。
• 使用 config('app.debug') 读取配置；切勿 include 配置文件。
• 使用 support\Log 记录日志（Log::info() / Log::channel('xx')->info()），不要使用 error_log 或 echo。

注意事项速查

不要	应该
使用 exit() / die() 结束请求	return response(...) 或抛出异常
$_GET / $_POST / $_SESSION	$request->get() / $request->post() / $request->session()
header() / setcookie()	$response->header() / $response->cookie()
无界静态数组	有界缓存（LRU）或 Redis
在单例中存储请求数据	局部变量 / support\Context（协程）
在应用代码中按请求创建定时器	在 config/process.php 中创建自定义进程
在协程下使用静态变量保存请求状态	support\Context::set() / get()

参考资料（按需阅读）

• 路由、控制器、请求 / 响应 API：references/routing-controller.md
• 中间件（洋葱模型、CORS、身份验证）：references/middleware.md
• 数据库、Redis、缓存、分页、事务：references/database-redis.md
• 自定义进程、WebSocket/TCP、定时器：references/custom-process.md
• 协程（webman v2）、Context、并发、连接池：references/coroutine.md
• 生命周期、内存泄漏及预防措施：references/memory-lifecycle.md
• 插件开发（库插件与应用插件）：references/plugin.md