README

基于 Workerman 5.x 的高性能 PHP 应用框架内核，专注于应用生命周期编排、配置管理、服务提供者（Provider）两阶段启动及包发现机制。

核心特性

高性能内核：基于 workerman/workerman ^5.1，支持 Fiber 协程。
生命周期编排：主进程与 Worker 进程引导流程分离，确保启动与运行时的稳定性。
配置管理：支持编译缓存、点分取值及目录扫描。
Provider 模型：两阶段启动（register -> boot），支持拓扑排序与超时保护。
包发现：基于 Composer 钩子自动发现中间件、命令、服务提供者及别名。
异常处理：统一封装，支持 Http/Console/Rpc 多上下文渲染。

环境要求

PHP >= 8.3（ext-json / ext-pcntl / ext-posix）
系统支持 Linux / macOS（pcntl 依赖，不支持 Windows）
revolt/event-loop ^1.0（Fiber 事件循环基座）
workerman/workerman ^5.1
psr/log ^3.0
fiberphp/contract / config / container / discovery / log / support（dev-master）

目录结构

src/                            # FiberPHP\Framework\（唯一根前缀）
├── helpers.php               # 全局助手函数（路径助手 + app/container/config/env/logger）
├── App.php                   # 运行时门面：项目入口唯一调用点
├── Kernel.php                # 应用生命周期编排器（主进程/Worker 引导）
├── WorkerFactory.php         # Worker 进程创建与事件回调绑定
├── Install.php               # 框架自身安装类（发布 config/log.php）
├── Bootstrap/                # FiberPHP\Framework\Bootstrap\
│   ├── BootGuard.php         # boot 阶段守卫（超时保护）
│   ├── BootstrapInterface.php # 引导步骤契约
│   ├── LogGlue.php           # 日志宿主注入胶水（绑定 LogManager 到容器）
│   └── Sorter.php            # Provider 拓扑排序
└── Exception/                # FiberPHP\Framework\Exception\
    ├── Exception.php         # 框架异常基类（默认 httpCode=500、消息不透传）
    └── Handler.php           # 统一异常处理器（Http/Console/Rpc 渲染）

命名空间收敛：framework 仅声明 1 个前缀 FiberPHP\Framework\ → src/，Bootstrap\ 与 Exception\ 作为其子命名空间。Attribute\（#[Package]）归 discovery 包；ProviderInterface 等契约归 contract 包；Container / Context / Facade 归 container 包；Config / Env 归 config 包。

核心组件

App — 运行时门面

App.php 是项目入口文件（如 start.php）的唯一调用点，负责加载配置并启动 Worker。提供两种运行模式：

方法	用途	是否 fork	是否进入事件循环
`run()`	生产启动（标准模式）	是	是
`bootstrap()`	一次性 CLI 脚本 / Cron	否	否

Kernel — 生命周期编排器

Kernel.php 是单例，纯编排职责，在正确的时机调用正确的步骤：

bootstrapMaster(): 主进程引导 —— 环境加载、错误处理、配置解析（仅执行一次）。
bootstrapWorker(): Worker 引导 —— 注册别名、加载文件、启动服务提供者（每进程执行）。
bootstrapForConsole(): Console 阶段引导 —— CLI 场景复用 Worker 引导流程。

关键组件：

Sorter: 使用 Kahn 算法对 Provider 进行拓扑排序。
BootGuard: 负责 boot 阶段的超时保护与异常降级。

配置与包发现

配置扫描/缓存由 config 包提供（Config::load() / buildCache()），包发现清单由 discovery 包提供（PackageManifest），framework 在引导阶段消费两者：读取配置、按清单注册 Provider / 命令 / 中间件 / 别名。

ProviderInterface — 服务提供者契约

采用两阶段生命周期：

register(): 容器绑定阶段（所有 Provider 必须先完成此阶段）。
boot($worker): 启动阶段，可访问其他服务。

通过 bootMeta() 声明调度元数据：

critical: 核心组件，失败将终止 Worker。
network: 涉及网络操作，启用超时保护。
timeout: 建议超时秒数。

Handler — 统一异常处理

Handler.php 覆盖 Http / Console / Rpc 等调用上下文的异常处理。提供 handle（report + render 一步完成）、report（日志记录）、render（响应渲染）方法，支持 renderable / reportable 闭包定制。

渲染规则（三码分离）：

HTTP 状态码：取 HttpCodeAware::getHttpCode()，未实现契约的异常兜底 500；
响应体业务码：$e->getCode() ?: 1（与 HTTP 状态码正交，不回退 HTTP 数字）；
消息透传：实现 UserFacingMessage 且 isMessageSafe()=true 的异常（如 http 包的 HttpException）生产环境透出消息，其余统一 Server Error 防内部细节泄漏；debug 模式全开；
字段级校验明细：实现 ValidationErrorsAware 时写入响应体 errors 字段（validate 包 422）。

业务层抛出 HTTP 语义异常统一使用 http 包异常类（HttpException / NotFoundHttpException）或 errcode() 助手；框架基类 Exception 仅供框架内部引导故障使用（默认 500、消息不透传）。

启动流程

以 App::run() 为例，整体分为 主进程引导与 Worker 引导两阶段。

sequenceDiagram
    participant Master as 主进程
    participant App as App
    participant Kernel as Kernel
    participant Factory as WorkerFactory
    participant WM as Workerman
    participant Worker as Worker 子进程
    Note over Master, WM: 阶段一：主进程引导（fork 前）
    Master ->> App: App::run()
    App ->> Kernel: bootstrapMaster()
    Note right of Kernel: ① 错误处理<br/>② 加载环境变量与配置<br/>③ 设置运行时参数
    App ->> App: configureWorker() & loadProcess()
    App ->> Factory: WorkerFactory::start() (绑定 onWorkerStart)
    App ->> WM: Worker::runAll()
    Note over Master, Worker: fork 边界
    WM ->> Worker: fork 子进程
    Note over Worker: 阶段二：Worker 引导（fork 后）
    Worker ->> Kernel: bootstrapWorker()
    Note right of Kernel: ① 注册错误处理<br/>② 重载配置<br/>③ 启动 Providers
    Worker ->> Factory: attachHandler()
    Note over Worker: 阶段三：请求处理

Provider 启动调度细节

BootGuard 对每个 Provider 的 boot 阶段进行如下控制：

解析 bootMeta() 获取配置。
若为 network 类型且配置了 timeout，使用 pcntl_alarm 设置超时。
异常处理：
- Critical: 重新抛出，终止 Worker 启动。
- 非 Critical: 记录 warning，降级继续。

拓扑排序

Sorter 排序策略（优先级从高到低）：

bootAfter() 声明的依赖关系（拓扑排序）。
app.boot_order 配置作为同层级 tiebreaker。
未声明的保持原发现顺序；存在循环依赖时追加到末尾。

运行模式

入口示例（start.php）：

#!/usr/bin/env php
<?php

use FiberPHP\Framework\App;

const BASE_PATH = __DIR__;

require_once __DIR__ . '/vendor/autoload.php';

App::run();

php start.php 直接进入 Worker::runAll()，支持 Workerman 原生命令参数：start [-d] / stop / reload / status / connections。

完整 CLI 能力由 console 包提供（fiberphp 入口由安装钩子自动发布）：

php fiberphp start [-d]        # 启动
php fiberphp stop|reload|restart|status|connections
php fiberphp package:discover  # 重建包发现清单（仅 CLI 支持）

配置说明

app.php

return [
    'debug'      => env('APP_DEBUG', false),
    'name'       => env('APP_NAME', 'fiberphp'),
    'boot_order' => [],  // 数字越小越早执行

    // 主进程引导列表（覆盖默认值）
    'master_bootstrap' => [],
    // Worker 引导列表（覆盖默认值）
    'worker_bootstrap' => [],
];

server.php

return [
    // 运行时文件路径
    'pid_file'    => runtime_path('logs/fiberphp.pid'),
    'status_file' => runtime_path('logs/fiberphp.status'),
    'log_file'    => runtime_path('logs/fiberphp.log'),
    'stdout_file' => runtime_path('logs/stdout.log'),

    // Worker 行为
    'stop_timeout'      => 2,                        // 平滑停止等待秒数
    'max_package_size'  => 10 * 1024 * 1024,         // 单个 TCP 包上限（10MB）
];

注意: 事件循环固定为 Workerman\Events\Fiber（基于 revolt/event-loop）。

应用接入

框架作为 Composer 依赖安装时，其钩子不会自动生效。应用方需在 composer.json 中注册脚本（骨架包 fiberphp/skeleton 已内置）：

{
  "scripts": {
    "post-autoload-dump": "FiberPHP\\Package\\PackageInstaller::discover",
    "pre-package-uninstall": "FiberPHP\\Package\\PackageInstaller::uninstall"
  }
}

post-autoload-dump: 依赖变更后触发，执行包清单（manifest）重建；pathRelation 声明的文件（如进程配置）仍会幂等拷贝到应用。
pre-package-uninstall: 包卸载前触发，清理已拷贝的发布文件。

各包自带的 config/ 默认配置由 config 包在 Config::load() 时自动扫描合并（装包即用），不再依赖拷贝发布；应用在自己的 config/ 放同名文件/键即可覆盖。进程文件（config/process/*.php）属保留目录、不进入配置合并，仍需通过 pathRelation 拷贝或进程发现。

包发现机制

子包在 composer.json 声明 extra.fiberphp.install。
对应的 Install 类使用 #[Package] 声明扩展点：

use FiberPHP\Attribute\Package;

#[Package(
    pathRelation: ['config/mysql.php' => 'config/mysql.php'],
    providers: [DbProvider::class],
    commands: [SomeCommand::class],
    middleware: [SomeMiddleware::class],
    aliases: ['MyFacade' => MyClass::class],
)]
class Install {}

全局函数

框架的 helpers.php 经 autoload.files 自动加载，全部全局函数定义于此：

函数	说明
`base_path()`, `app_path()`, `config_path()`, `route_path()`, `runtime_path()`, `public_path()`	路径助手（依赖 `BASE_PATH` 常量）
`app($abstract, $constructor)`	获取容器实例或解析依赖
`container()`	获取 Container 单例
`config($key, $default)`	读取配置（dot-key）
`env($key, $default)`, `env_int($key, $default)`	读取环境变量
`logger()`	获取 LoggerInterface 实例（永不抛出）

命名冲突防护: 所有函数均通过 if (!function_exists(...)) 保护性定义。

License

MIT

fiberphp / framework

Package info

Security

Statistics