# skeleton

**Repository Path**: fiberphp/skeleton

## Basic Information

- **Project Name**: skeleton
- **Description**: 🚀 FiberPHP 应用骨架 —— 高性能 PHP 协程框架，基于 Workerman + PHP 8.1+ Fiber，开箱即用。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP 应用骨架

FiberPHP 应用骨架包，基于 [FiberPHP](https://gitee.com/fiberphp/framework) 框架与 Workerman 构建，用于通过
`composer create-project` 快速创建新项目。

## 环境要求

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

## 快速开始

```bash
# 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 包安装时自动发布，无需手工创建）：

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

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

## Provider 开发说明

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

```php
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/database`）通过 Composer `post-autoload-dump` 钩子（`FiberPHP\Package\PackageInstaller::discover`
）自动注册到 `PackageManifest`，无需手动在应用配置中声明。

## 异常处理自定义

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

```php
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` 对象。

## License

[MIT](LICENSE)