README

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

环境要求

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

快速开始

# 1. 创建项目（依赖已随 create-project 自动安装）
composer create-project fiberphp/skeleton 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/
│   ├── Controller/              # 控制器目录（业务路由推荐注解声明）
│   ├── ExceptionHandler.php     # 自定义异常处理（继承 framework Handler）
│   ├── Middleware/              # 应用中间件
│   └── Provider/
│       └── AppProvider.php      # 应用级 Provider（框架按约定自动发现）
├── config/
│   ├── app.php                  # 应用配置（debug / name / boot_order / master_bootstrap / worker_bootstrap）
│   ├── log.php                  # 日志配置（默认通道 / 缓冲刷盘 / 敏感字段脱敏）
│   ├── server.php               # Workerman 全局属性（pid_file / 超时 / 包大小），事件循环固定 Fiber
│   ├── process/                 # 进程声明发现目录（子包安装时自动注入，如 http 的 config/process/http.php）
│   └── command/                 # 控制台命令发现目录（按需创建，子包/应用放置命令注册文件）
├── docker/                      # Docker 构建与部署配置（Dockerfile.base / Dockerfile / docker-compose.yml）
├── public/                      # 静态资源目录
├── route/
│   └── app.php                  # 闭包路由（探针/健康检查等，需 fiberphp/router）
├── runtime/                     # 运行时目录（日志、缓存）
├── tests/
│   └── ExampleTest.php         # 测试示例
├── .dockerignore                # Docker 构建上下文排除规则
├── .env.example                 # 环境变量模板
├── composer.json
├── Makefile
├── fiberphp                     # CLI 入口（安装 fiberphp/console 时自动发布，勿手工创建）
└── start.php                    # 主进程入口

配置说明

环境变量（.env）

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

变量	说明	默认值
`APP_NAME`	应用名称	`fiberphp`
`APP_DEBUG`	调试模式（true/false）	`false`（.env 模板置 true 便于本地开发，生产请置 false）
`SERVER_LISTEN`	HTTP 监听地址	`http://0.0.0.0:8787`（.env 模板为 8080）
`SERVER_COUNT`	HTTP Worker 进程数	`auto`（按 CPU 核心数）

配置文件（config/）

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

config/
├── app.php                   # 应用自身：debug、name、providers/boot_order、master/worker bootstrap
├── log.php                   # 日志配置（默认通道、缓冲刷盘、敏感字段脱敏）
├── server.php                # Workerman Worker 全局属性（pid_file、stop_timeout…），事件循环固定 Fiber
├── process/                  # 进程声明发现目录（不进入 config 顶层键，App 专用）
│   ├── http.php              #   fiberphp/http 安装后注入
│   └── monitor.php           #   fiberphp/monitor 安装后注入
└── command/                  # 控制台命令发现目录（不进入 config 顶层键，按需创建，框架扫描时容错）

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

每类文件的详细约定：

子包配置（如 config/http.php、config/database.php）：通过 config('http.xxx') / config('database.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（目录不存在时跳过）。同名进程冲突会抛出异常，要求显式改名。子包安装时自动注入其进程配置（如 fiberphp/http 注入 config/process/http.php），应用无需手工创建。
config/command/：控制台命令发现目录。每个子文件返回命令类 class-string[] 或 [cmdName => class-string]；与 PackageManifest 中 #[Package(commands: [])] 的结果合并去重。目录按需创建即可（框架扫描时容错，不存在则跳过）；子包的命令优先通过 #[Package(commands: [])] 自动注册，不依赖该目录。
route/（根目录）：闭包/数组回调路由文件目录，安装 fiberphp/router 后由其扫描加载；业务路由推荐控制器注解。

常用命令

通过 Makefile 简化操作：

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

CLI 入口

安装依赖后，项目根目录会生成可执行入口 fiberphp（由 fiberphp/console 包安装时自动发布，无需手工创建）：

./fiberphp              # 查看可用命令
./fiberphp status       # 查看 Worker 状态
./fiberphp restart      # 重启 Worker
./fiberphp stop         # 停止 Worker

应用自定义命令可通过 #[Package(commands: [])] 包发现或在 config/command/ 放置注册文件注册。

Provider 开发说明

Provider 是 FiberPHP 的服务提供者。推荐继承 FiberPHP\Container\ServiceProvider 基类（而非裸实现 ProviderInterface）：两阶段生命周期、boot 元数据、配置/日志/绑定样板全部由基类收敛：

namespace App\Provider;

use FiberPHP\Container\ServiceProvider;

class MyProvider extends ServiceProvider
{
    // boot 调度元数据：用属性声明即可（基类 bootMeta() 自动派生）
    protected bool $critical = false;      // true 时 boot 异常终止 Worker 启动
    protected bool $network = false;       // boot 是否可能发起网络建连
    protected int|float|null $bootTimeout = null; // 网络探活超时秒数；null 禁用 alarm

    // 1. 注册阶段：仅做容器绑定，不要访问其他服务
    public function register(): void
    {
        // singleton() 一次绑定 实现类 + 别名/契约，共享同一单例
        $this->singleton(
            MyService::class,
            fn () => new MyService($this->configValue('my', [])),
            'my',
            MyServiceInterface::class,
        );
    }

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

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

基类提供的受保护方法：

container()：容器实例；config() / configValue($key, $default)：读配置（进程内 memoize，register/boot 共享一次解析）。
logger()：日志器（容器绑定优先，未绑定兜底 NullLogger）。
singleton($concrete, $factory, ...$keys)：绑定单例并把别名/契约键全部指向同一实例。

元数据语义：

$critical（默认 false）：true 时 boot 抛出的异常终止 Worker 启动；false 时降级为 warning 日志并跳过。
$network（默认 false）：boot 是否可能进行网络建连。仅当 true 且 $bootTimeout 为正数时才启用 pcntl_alarm 超时保护。
$bootTimeout（默认 null）：最大允许执行秒数；正数启用 alarm 强制中断，null 显式禁用。

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

异常处理自定义

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

namespace App;

use FiberPHP\Framework\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 对象。

业务异常怎么抛

业务代码无需自定义异常类，直接使用 http 包异常与助手（消息自动透传，无需自定义 Handler）：

use FiberPHP\Http\Exception\NotFoundHttpException;
use FiberPHP\Http\Exception\HttpException;

throw new NotFoundHttpException('商品不存在');        // 404
throw new HttpException(400, '分类编码已存在');        // 400 / 任意 4xx、5xx
throw new ValidateException($errors);                 // 422（fiberphp/validate，自动带 errors 明细）
errcode(10401);                                       // 400 + 业务码，消息查 config/error.php 字典

未知异常（DB/Redis 等）生产环境统一收敛为 Server Error（真实细节进日志），debug 模式全开。

License

MIT

fiberphp / skeleton

Package info

Security

Statistics