README

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

核心特性

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

环境要求

PHP: >= 8.3
系统: Linux / macOS（依赖 pcntl 扩展，不支持 Windows）
依赖:
- workerman/workerman ^5.1
- fiberphp/container dev-master
- psr/log ^3.0

目录结构

framework/
├── composer.json
└── src/
    ├── App.php                   # 运行时门面：项目入口唯一调用点
    ├── Kernel.php                # 应用生命周期编排器（主进程/Worker 引导）
    ├── Config.php                # 配置加载与点分取值（含编译缓存）
    ├── Env.php                   # .env 解析与环境变量管理
    ├── Context.php               # 请求级上下文容器（Fiber 隔离）
    ├── WorkerFactory.php         # Worker 进程创建与事件回调绑定
    ├── PackageManifest.php       # 统一包发现清单
    ├── PackageInstaller.php      # Composer 钩子执行者
    ├── helpers.php               # 全局函数
    ├── Logger.php                # 最小 Logger 实现
    ├── Pipeline.php              # 中间件管道构建器
    ├── Attribute/
    │   └── Package.php           # 包扩展声明 Attribute
    ├── Bootstrap/
    │   ├── BootGuard.php         # boot 阶段守卫（超时保护）
    │   └── Sorter.php            # Provider 拓扑排序
    ├── Contract/
    │   ├── BootstrapInterface.php
    │   └── ProviderInterface.php
    └── Exception/
        ├── Exception.php
        ├── Handler.php
        └── BusinessException.php

核心组件

App — 运行时门面

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

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

Kernel — 生命周期编排器

Kernel.php 是单例，纯编排职责，在正确的时机调用正确的步骤。核心流程分为：

主进程引导 (bootstrapMaster): 环境加载、错误处理、配置解析（仅执行一次）。
Worker 引导 (bootstrapWorker): 注册别名、加载文件、启动服务提供者（每进程执行）。
Provider 生命周期: 负责 ProviderInterface 的两阶段调度。

关键组件：

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

Config — 配置管理

Config.php 递归扫描 config/ 目录，支持：

编译缓存: buildCache() 生成 runtime/cache/config.php。
点分取值: config('app.debug')。
保留目录: process/, command/, routes/ 不进入顶层配置，由专用发现器独立扫描。

ProviderInterface — 服务提供者契约

采用两阶段生命周期：

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

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

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

PackageManifest — 包发现

PackageManifest.php 负责统一发现各子包的扩展点：

发现来源: vendor/composer/installed.json 中的 extra.fiberphp.install 声明。
缓存: 结果缓存于 runtime/cache/packages.php。
重建: 支持 php start.php package:discover 命令手动重建。

Handler — 统一异常处理

Handler.php 覆盖 Http / Console / Rpc 三种调用上下文的异常处理。提供 handle（report + render 一步完成）、report（日志记录）、render（响应渲染）方法。

Pipeline — 中间件管道

Pipeline.php 按洋葱模型构建中间件管道，并支持 PHP Fiber 协程：

build(): 构建闭包（可缓存）。
run(): 在独立 Fiber 中执行管道，支持异步挂起与恢复。

启动流程

以 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/>③ 设置运行时参数
    deactivate Kernel

    App->>App: configureWorker() & loadProcess()
    App->>Factory: WorkerFactory::start() (绑定 onWorkerStart)
    deactivate App

    App->>WM: Worker::runAll()
    
    Note over Master,Worker: fork 边界

    WM->>Worker: fork 子进程
    activate Worker

    Note over Worker: 阶段二：Worker 引导（fork 后）
    Worker->>Kernel: bootstrapWorker()
    Note right of Kernel: ① 注册错误处理<br/>② 重载配置<br/>③ 启动 Providers
    deactivate Kernel

    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\App;

const BASE_PATH = __DIR__;

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

App::run();

CLI 命令：

启动: php start.php start
后台: php start.php start -d
重启: php start.php reload
停止: php start.php stop
包发现: php start.php package:discover

配置说明

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() . '/app.pid',
    'stdout_file'  => runtime_path() . '/logs/stdout.log',
    'log_file'     => runtime_path() . 'logs/workerman.log',
    'stop_timeout' => 2,
    // ... 其他 Workerman 配置
];

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

应用接入

框架作为 Composer 依赖安装时，其钩子不会自动生效。应用方需在 composer.json 中注册脚本：

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

post-autoload-dump: 依赖变更后触发，执行配置拷贝与包清单重建。
pre-package-uninstall: 包卸载前触发，清理已拷贝的配置文件。

包发现机制

子包在 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：

函数	说明
`base_path()`, `app_path()`, `config_path()`, `runtime_path()`	路径助手
`config($key, $default)`	读取配置
`app($abstract, $constructor)`	获取容器实例或解析依赖
`container()`	获取 Container 单例
`env($key, $default)`, `env_int($key, $default)`	读取环境变量
`logger()`	获取 LoggerInterface 实例
`copy_dir()`, `remove_dir()`, `cpu_count()`	文件/系统助手

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

fiberphp / framework

Maintainers

Package info

Statistics

Security