# framework

**Repository Path**: fiberphp/framework

## Basic Information

- **Project Name**: framework
- **Description**:  🚀 FiberPHP —— 高性能 PHP 协程框架，基于 Workerman + PHP 8.4+ Fiber，模块化设计，开箱即用。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP Framework

基于 [Workerman 5.x](https://github.com/walkor/workerman) 的高性能 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
    ├── Handler.php
    └── BusinessException.php
```

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

## 核心组件

### App — 运行时门面

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

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

### Kernel — 生命周期编排器

[Kernel.php](src/Kernel.php) 是单例，纯编排职责，在正确的时机调用正确的步骤：

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

关键组件：

- [Sorter](src/Bootstrap/Sorter.php): 使用 Kahn 算法对 Provider 进行拓扑排序。
- [BootGuard](src/Bootstrap/BootGuard.php): 负责 `boot` 阶段的超时保护与异常降级。

### 配置与包发现

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

### ProviderInterface — 服务提供者契约

采用两阶段生命周期：

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

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

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

### Handler — 统一异常处理

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

## 启动流程

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

```mermaid
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](src/Bootstrap/BootGuard.php) 对每个 Provider 的 `boot` 阶段进行如下控制：

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

### 拓扑排序

[Sorter](src/Bootstrap/Sorter.php) 排序策略（优先级从高到低）：

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

## 运行模式

入口示例（`start.php`）：

```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](../console) 包提供（`fiberphp` 入口由安装钩子自动发布）：

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

## 配置说明

### app.php

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

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

### server.php

```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` 已内置）：

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

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

## 包发现机制

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

```php
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](src/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](LICENSE)