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-mbstring / ext-pcntl）
系统支持 Linux / macOS（pcntl 依赖，不支持 Windows）
revolt/event-loop ^1.0（Fiber 事件循环基座）
workerman/workerman ^5.1
psr/log ^3.0 / psr/container ^2.0
fiberphp/helper（Arr/Str/Collection/Pipeline）

平台差异: 文件变更监控（reload）在 Linux / macOS 均默认启用（守护模式 -d 下关闭）；内存监控依赖 Linux /proc 文件系统，macOS 下自动跳过。

安装

composer require fiberphp/framework

包源码托管在 Gitee（gitee.com/fiberphp/framework）。若尚未发布到 Packagist，在应用 composer.json 中添加 VCS 仓库源：

{
    "repositories": [
        { "type": "vcs", "url": "https://gitee.com/fiberphp/framework.git" }
    ]
}

当前各包以 dev-master 互依赖，应用需设置 "minimum-stability": "dev"（骨架包 fiberphp/skeleton 已内置）；发布稳定版后将切换为语义化版本约束。

运行模式

入口示例（start.php）：

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

use FiberPHP\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 能力由 framework 内置 Console 组件提供：

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

配置说明

app.php

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

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

    // 应用级 ServiceProvider
    'providers' => [],
];

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\\Installer::discover",
    "pre-package-uninstall": "FiberPHP\\Package\\Installer::uninstall"
  }
}

post-autoload-dump: 依赖变更后触发，扫描已安装子包并自动注册其 Provider、命令、配置等扩展点。
pre-package-uninstall: 包卸载前触发，清理已拷贝的发布文件。

各包自带的 config/ 默认配置装包即用（自动合并）；应用在自己的 config/ 放同名文件/键即可覆盖。进程文件（config/process/*.php）不进入配置合并，由子包安装时自动拷贝或按进程发现。

包发现机制

子包在 composer.json 的 extra.fiberphp 下纯声明扩展点，框架经 Composer 钩子自动发现：

{
  "extra": {
    "fiberphp": {
      "pathRelation": {"config/mysql.php": "config/mysql.php"},
      "providers": ["FiberPHP\\Db\\DbProvider"],
      "commands": ["FiberPHP\\Db\\Command\\SomeCommand"],
      "middleware": ["FiberPHP\\Db\\SomeMiddleware"],
      "aliases": {"MyClass": "FiberPHP\\Db\\MyClass"}
    }
  }
}

pathRelation：装包时拷贝到应用目录的文件映射 [源相对路径 => 目标相对路径]（config/*.php 默认配置经此发布，应用同名文件覆盖）。
providers / commands / middleware / aliases：类名列表与别名绑定，全部可选，缺省为空。

ServiceProvider — 服务提供者

各包 Provider 继承 FiberPHP\ServiceProvider 基类，采用两阶段生命周期：

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

通过属性声明 boot 调度元数据：

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

启动顺序控制：Provider 可实现静态方法 bootAfter(): list<class-string> 声明必须先完成 boot() 的依赖 Provider。

class RouterProvider extends ServiceProvider
{
    public static function bootAfter(): array
    {
        return [HttpProvider::class];
    }

    public function boot(?object $worker = null): void
    {
        // 此时 HttpProvider 的服务已就绪
    }
}

全局函数

框架的 helpers.php 经 autoload.files 自动加载，全部全局函数如下：

函数	说明
`base_path()`, `app_path()`, `config_path()`, `route_path()`, `runtime_path()`, `public_path()`	路径助手（依赖 `BASE_PATH` 常量）
`app($abstract, $constructor)`	获取容器实例（无参）或解析依赖
`env($key, $default)`	读取环境变量原始值
`logger()`	获取 LoggerInterface 实例（永不抛出）

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

静态适配器（FiberPHP\）

FiberPHP\ 命名空间下的静态类是框架各子系统的静态状态持有者，应用层直接 use 调用：

类	说明
`FiberPHP\Config`	配置仓库（由 fiberphp/config 包提供）：`Config::get/has/all` + `load/loadFromDir`
`FiberPHP\Log`	日志管理器（框架内置，Monolog 3）：`Log::debug/info/error` + `Log::channel('db')` 命名通道
`FiberPHP\Env`	环境变量（由 fiberphp/config 包提供）：`Env::get/load/loadCascade/reset`，容器装配前即可用
`FiberPHP\Redis\Redis`	Redis 连接池代理（由 fiberphp/redis 包提供，需安装）：`Redis::connection('cache')`
`FiberPHP\Cache\Cache`	缓存门面（PSR-16，由 fiberphp/cache 包提供，需安装）：`Cache::store('session')`
`FiberPHP\Context`	请求级上下文：`Context::set/get/onDestroy`（按 Fiber 隔离）

use FiberPHP\Config;
use FiberPHP\Log;

Config::get('app.debug');
Log::error('消息', ['key' => $value]);
Log::channel('db')->info('query executed');

logger() 助手返回 LoggerInterface（PSR-3 方法）；需要 channel() 等管理器 API 时用 FiberPHP\Log。Log 为框架内置；Redis / Cache 门面由 fiberphp/redis、fiberphp/cache 包提供（配置分别读取 redis / cache 配置键），其他组件包由各自包提供独立适配器。

异常处理

业务层抛出 HTTP 语义异常统一使用 fiberphp/http 包的异常类（HttpException / NotFoundHttpException）或 errcode() 助手；框架基类 Exception 仅供框架内部引导故障使用。

License

MIT

fiberphp / framework

Package info

Security

Statistics