用途
本技能用于在 Laravel Octane 环境下开发应用。Octane 是长驻 PHP 工作进程服务器,支持 Swoole、FrankenPHP、RoadRunner 三种驱动,应用容器只启动一次并在多个请求之间复用,因此 PHP-FPM 下的许多假设会引发 Octane 特有缺陷。技能给出编写代码时应遵循的持久性规则,并提醒具体细节以对应版本的官方文档为准。
主要能力与规则
先检测驱动
读取 config('octane.server') 确定驱动是 swoole、roadrunner 还是 frankenphp。Octane::concurrently()、Octane::table()、octane 缓存存储以及 ticks/interval 仅在 Swoole 上可用,需用该检查做条件保护。
状态隔离(所有驱动)
避免在单例或静态属性中存放请求相关状态,否则前一请求的状态可能泄漏到后续请求。优先使用 scoped 绑定、延迟解析,或将服务加入 config/octane.php 的 flush 列表。通过方法参数或 request() 助手注入 Request,不要在构造时捕获。必须保留的静态状态可在 RequestTerminated 事件中重置。框架已刷新认证、会话、Cookie 等核心状态,应用自身状态需自行负责。
内存(所有驱动)
工作进程长期存活,未被释放的引用会累积直至进程崩溃。应设置 max-requests 或 max-jobs 回收上限作为最后防线;事件监听器在服务提供者中注册,而非请求处理器内;静态数组需在生命周期监听器中清空或 flush;注意单例闭包中捕获大型对象(如 Eloquent 模型)导致永久持有。
并发(仅 Swoole)
先做驱动判断,再用 Octane::concurrently() 并行执行闭包,结果按输入顺序返回。闭包会被序列化交给任务工作进程,因此应传递标量 ID 并在闭包内重新获取模型,不要捕获 $this 或不可序列化状态。需要在 Octane 重新抛出前转换或记录异常时,应在闭包内部捕获。
Swoole Table 与 octane 缓存(仅 Swoole)
表需在启动时预分配('name:maxRows'),无法调整大小,超出上限可能静默失败;数据在进程重启后丢失,不能替代 Redis 或数据库。无事务,原子计数使用 incr()/decr()。octane 缓存存储仅适用于临时高频数据,使用同一共享内存,不具备持久性。
测试(所有驱动)
在没有真实服务器时测试 concurrently()、table 和 ticks,应验证正确性而非并行性,因为闭包在测试中可能顺序执行。断言之间调用 $this->refreshApplication() 模拟每请求的 scoped 绑定刷新,证明状态不泄漏。Swoole 专属测试需用 extension_loaded('swoole') || extension_loaded('openswoole') 做保护,两者都不可用时跳过。
常见陷阱
- 不要在应用完全启动前于低层工作进程启动代码中解析 config()、app('config') 等容器服务,尤其未缓存配置时;也不应假定已运行 php artisan config:cache。
- 绝不在单例、静态属性或自定义 guard 绑定中捕获 Auth::user(),应按请求解析认证状态并将有状态服务加入 flush 列表。
- 关闭在框架管理池之外打开的每请求 Redis、数据库和 HTTP 客户端连接,可在 RequestTerminated 监听器中重置。
- 不要读取 PHP 超全局变量($_GET、$_POST、$_SERVER),应使用 Request 对象。
- 不要在 concurrently() 闭包中捕获不可序列化值(PDO 连接、Eloquent 模型、$this)。
- 修复请求启动期间产生的 PHP 警告,在 FrankenPHP 上可能导致工作进程关闭。
- 修改代码、服务提供者、环境变量或配置后需重载工作进程(octane:reload、重启,或本地开发使用 --watch)。
参考与版本核对
具体安装命令、Caddyfile 和 .rr.yaml 配置、服务器参数、方法签名等以 Laravel Boost 的 search-docs 工具(限定已安装的 laravel/octane 版本)及官方文档为准。技能列出参考地址:Laravel Octane 文档 https://laravel.com/docs/octane;FrankenPHP 文档 https://frankenphp.dev/docs/(worker 模式 /docs/worker/、Laravel /docs/laravel/、config/Caddyfile /docs/config/、已知问题 /docs/known-issues/);OpenSwoole 文档 https://openswoole.com/docs;RoadRunner 文档 https://docs.roadrunner.dev/docs(PHP worker /docs/php-worker/worker.md、简介 /docs/general/about.md)。
验证清单
确认 config('octane.server') 与任何仅 Swoole 代码所假设的驱动一致;确认没有请求派生状态存于单例或静态属性而未做 scoped、flush 或重置处理;确认已配置工作进程回收上限(max_requests 或 max_jobs)。
限制
本技能的具体安装步骤、配置示例与精确 API 语法未在资料中提供,需按已安装版本查询官方文档。