README

FiberPHP 应用骨架包，基于 FiberPHP 框架与 Workerman 构建，用于通过 composer create-project 快速创建新项目。

环境要求

PHP >= 8.3
必需扩展：pcntl、posix（Workerman 进程模型依赖）
Composer 2.x

快速开始

# 1. 创建项目（依赖已随 create-project 自动安装）
composer create-project fiberphp/app my-project --no-interaction

# 2. 进入项目目录
cd my-project

# 3. 准备环境配置
cp .env.example .env

# 4. 启动服务（前台运行）
php start.php start

默认监听 http://0.0.0.0:8080，访问 http://127.0.0.1:8080 即可。

目录结构

my-project/
├── app/
│   ├── ExceptionHandler.php     # 自定义异常处理（继承 framework Handler）
│   ├── Middleware/              # 应用中间件
│   └── Provider/
│       └── AppProvider.php      # 应用级 Provider（示例）
├── config/
│   ├── app.php                  # 应用配置（debug / name / boot_order / master_bootstrap / worker_bootstrap）
│   ├── server.php               # Workerman 全局属性（pid_file / 超时 / 包大小），事件循环固定 Fiber
│   ├── process/                 # 进程声明发现目录（子包 fiberphp/{crontab,queue,http} 自动注入）
│   └── command/                 # 控制台命令发现目录（子包 fiberphp/{crontab,queue} 自动注入）
├── docker/                      # Docker 构建与部署配置（Dockerfile.base / Dockerfile / docker-compose.yml）
├── public/                      # 静态资源目录
├── runtime/                     # 运行时目录（日志、缓存）
├── tests/
│   └── ExampleTest.php         # 测试示例
├── .dockerignore                # Docker 构建上下文排除规则
├── .env.example                 # 环境变量模板
├── composer.json
├── Makefile
└── start.php                    # 主进程入口

配置说明

环境变量（.env）

复制 .env.example 为 .env 后按需修改：

变量	说明	默认值
`APP_NAME`	应用名称	`fiberphp`
`APP_DEBUG`	调试模式（true/false）	`true`
`SERVER_LISTEN`	HTTP 监听地址（需 fiberphp/http）	`http://0.0.0.0:8080`
`SERVER_COUNT`	HTTP Worker 进程数（需 fiberphp/http）	`auto`（按 CPU 核心数）

配置文件（config/）

整体结构按「配置键 / 进程发现 / 命令发现」分区：

config/
├── app.php                   # 应用自身：debug、name、providers/boot_order、master/worker bootstrap
├── server.php                # Workerman Worker 全局属性（pid_file、stop_timeout…），事件循环固定 Fiber
├── process/                  # 进程声明发现目录（不进入 config 顶层键，App 专用）
│   ├── crontab.php           #   fiberphp/crontab 安装后注入
│   └── queue.php             #   fiberphp/queue 安装后注入
└── command/                  # 控制台命令发现目录（不进入 config 顶层键）
    ├── crontab.php           #   fiberphp/crontab 安装后注入
    └── queue.php             #   fiberphp/queue 安装后注入

子包级配置文件 config/crontab.php、config/queue.php、config/http.php 在安装对应子包后，由 PackageManifest 的 pathRelation 一并注入，出现在 config/ 顶层。

每类文件的详细约定：

子包配置（config/http.php、config/queue.php、config/crontab.php 等）：通过 config('http.xxx') / config('queue.xxx') 等 dot-key 读取。由对应子包在 composer install 时通过 PackageManifest 的 pathRelation 自动注入；文件已存在时不覆盖，保留用户自定义。
config/server.php：Workerman Worker 全局属性（pid_file、status_file、log_file、stdout_file、stop_timeout、max_package_size）。默认写入 runtime/logs/ 目录。事件循环固定为 Workerman\Events\Fiber（基于 revolt/event-loop），由框架硬编码，不可配置。
config/process/：进程声明发现目录。每个子文件返回 [进程名 => ['handler' => ..., 'listen' => ..., 'count' => ...]] 结构。框架仅扫描 config/process/*.php，不再识别 **/process.php 旧文件名。同名进程冲突会抛出异常，要求显式改名。
config/command/：控制台命令发现目录。每个子文件返回命令类 class-string[] 或 [cmdName => class-string]；与 PackageManifest 中 #[Package(commands: [])] 的结果合并去重。
config/routes/（保留，fiberphp/http 发布后启用）：路由文件发现目录，不进入 Config 顶层键。

常用命令

通过 Makefile 简化操作：

命令	说明
`make install`	安装 Composer 依赖
`make start`	前台启动服务
`make start-daemon`	以守护进程方式启动
`make stop`	停止服务
`make reload`	平滑重启
`make test`	运行 PHPUnit 测试

Provider 开发说明

Provider 是 FiberPHP 的服务提供者，实现 FiberPHP\Contract\ProviderInterface，拥有两阶段生命周期：

namespace App\Provider;

use FiberPHP\Contract\ProviderInterface;

class MyProvider implements ProviderInterface
{
    // 1. 注册阶段：仅做容器绑定，不要访问其他服务
    public function register(): void
    {
        // app()->bind(MyService::class, fn() => new MyService());
    }

    // 2. 启动阶段：可访问已注册服务，执行路由注册、事件监听、探活等
    public function boot(?object $worker = null): void
    {
        // $worker 为 Workerman\Worker 实例（CLI 命令场景可能为 null）
    }

    // 声明 boot() 调度元数据，供 BootGuard 决定超时保护与异常分类策略
    public function bootMeta(): array
    {
        return [
            'critical' => false,    // true 时 boot 异常终止 Worker 启动
            'network'  => false,    // 是否可能产生新的网络建连
            'timeout'  => null,     // 网络探活超时秒数；null 显式禁用 alarm
        ];
    }

    // 可选：声明 boot 依赖（必须先完成 boot 的 Provider 类名数组）
    public static function bootAfter(): array
    {
        return [];
    }
}

bootMeta() 字段说明：

critical（bool，默认 false）：核心基础设施标记。true 时 boot 抛出的异常会终止 Worker 启动；false 时降级为 warning 日志并跳过。
network（bool，默认 false）：boot 是否可能进行网络建连。仅当 true 且 timeout !== null 时才启用 pcntl_alarm 超时保护。
timeout（float|int|null）：最大允许执行秒数。正数启用 alarm 强制中断；null 显式禁用 alarm（适用于复用已有连接或自行处理超时）。

子包（如 fiberphp/http、fiberphp/db）通过 Composer post-autoload-dump 钩子（FiberPHP\PackageInstaller::discover）自动注册到 PackageManifest，无需手动在应用配置中声明。

异常处理自定义

应用层通过 app/ExceptionHandler.php 自定义异常渲染。该类继承 FiberPHP\Exception\Handler，框架在 Handler::resolve() 中自动发现 App\ExceptionHandler：

namespace App;

use FiberPHP\Exception\Handler;

class ExceptionHandler extends Handler
{
    // 可覆盖以下方法自定义输出：
    // - renderHttp(Throwable $e, mixed $request = null): mixed   HTTP 上下文
    // - renderConsole(Throwable $e): string                      控制台上下文
    // - renderRpc(Throwable $e): array                           RPC 上下文
    // - shouldReport(Throwable $e): bool                        是否上报（配合 $dontReport）

    protected array $dontReport = [
        // 不需上报的异常类型
    ];
}

render() 入口按上下文（http / console / rpc）分发到对应方法，并保证永不抛出。fiberphp/http 包会覆盖 renderHttp() 返回 Response 对象。

License

MIT License，详见 LICENSE。

fiberphp / app

Maintainers

Package info

Statistics

Security