# contract

**Repository Path**: fiberphp/contract

## Basic Information

- **Project Name**: contract
- **Description**: 📜 FiberPHP 契约包 —— 跨包公共接口，零依赖，所有子包通过此包解耦
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP Contract

FiberPHP 契约包 —— 跨包公共接口集合。零依赖（仅 PHP），是整个 FiberPHP 包体系中的**最低层依赖**：所有子包通过实现这里的接口互相解耦，而非直接依赖具体实现包。

## 环境要求

- PHP >= 8.3

## 安装

```bash
composer require fiberphp/contract
```

## 接口清单

| 接口 | 用途 |
|---|---|
| `ProviderInterface` | 服务提供者两阶段生命周期：`register()`（注册绑定）→ `boot()`（启动逻辑），支持 `bootMeta()` 声明网络依赖/超时/critical 分类 |
| `ConfigRepository` | 配置仓库抽象：`get()` / `has()` / `set()`，组件包通过容器解析配置而不依赖全局 `config()` helper |
| `CacheInterface` | 缓存抽象：get / set / delete / has / increment / decrement / tag，消费者通过它注入缓存而不依赖具体缓存实现 |
| `TaggedCacheInterface` | 标签缓存作用域：set / clear，由 `CacheInterface::tag()` 返回 |
| `LockInterface` | 分布式锁三原语：tryLock / release / renew |
| `RateLimiterInterface` | 固定窗口限流计数：attempt |
| `SessionStoreInterface` | 会话存储：read / write / destroy / gc |
| `RedisClient` | Redis 客户端最小契约：connect / close + `__call` 命令透传（Sync/Async 双实现透明切换） |
| `RedisFactory` | Redis 连接工厂：按连接名解析协程自适应客户端 |
| `Exception\ExceptionHandler` | 异常处理生命周期：handle / report / render / shouldReport |
| `Exception\HttpCodeAware` | 异常实现此接口即可声明对应 HTTP 状态码，无需继承框架异常基类 |
| `Exception\DebugDataAware` | 异常实现此接口即可携带结构化调试数据并控制调试信息暴露 |
| `Exception\UserFacingMessage` | 异常实现此接口（`isMessageSafe(): bool`）即声明消息可在非 debug 模式透传给用户；未实现的异常统一收敛为 `Server Error` 防内部细节泄漏 |
| `Exception\ValidationErrorsAware` | 异常实现此接口（`getErrors(): array`）即携带字段级校验明细，Handler 渲染时写入响应体 `errors` 字段（如 validate 包 422） |

## 基本用法

### 实现契约（子包视角）

以缓存实现为例，实现类依赖契约而非反向依赖调用方（cache 包的 `Cache` 类即如此）：

```php
namespace FiberPHP\Cache;

use FiberPHP\Contract\CacheInterface;

class Cache implements CacheInterface
{
    public function get(string $key, mixed $default = null): mixed { /* ... */ }
    public function set(string $key, mixed $value, int $ttl = 0): bool { /* ... */ }
    // ...
}
```

### 消费契约（跨包解耦）

消费者包只需 `require fiberphp/contract`，通过构造函数注入 `CacheInterface` 即可使用缓存，不依赖任何具体实现包（如 fiberphp/cache）：

```php
use FiberPHP\Contract\CacheInterface;

class QueryCache
{
    public function __construct(
        private readonly CacheInterface $cache,
    ) {
    }
}
```

### 服务提供者契约

```php
use FiberPHP\Contract\ProviderInterface;

class MyProvider implements ProviderInterface
{
    public function register(): void
    {
        // 注册绑定（所有 register 先于任何 boot 执行）
    }

    public function boot(?object $worker = null): void
    {
        // 建立连接、路由注册等启动逻辑（可依赖其他已注册服务）
    }

    public function bootMeta(): array
    {
        return ['network' => true, 'timeout' => 5, 'critical' => true];
    }
}
```

`bootMeta()` 的元数据由 `FiberPHP\Framework\Bootstrap\BootGuard` 消费：`network=true` 且 `timeout` 非 null 时启用 pcntl_alarm 超时保护（`timeout=null` 显式跳过），`critical=true` 的 Provider 启动失败将终止进程。

## 依赖关系

```
fiberphp/contract        ← 本包（零依赖，包体系最低层）
  ↑
所有 FiberPHP 组件包      ← 通过实现/消费这里的接口互相解耦
```

典型消费方：framework 调度 `ProviderInterface` 生命周期，异常处理器实现 `ExceptionHandler` 契约，缓存/锁/限流/会话等组件通过对应接口注入而不依赖具体实现。

## License

[MIT](LICENSE)