README

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

环境要求

PHP >= 8.3

安装

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 类即如此）：

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）：

use FiberPHP\Contract\CacheInterface;

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

服务提供者契约

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

fiberphp / contract

Maintainers

Package info

Statistics

Security