Download the PHP package kode/limiting without Composer

kode/limiting

高性能 PHP 限流器，支持令牌桶、漏桶、滑动窗口、滑动窗口计数器、固定窗口计数器与多规则组合限流；内置内存 / APCu / Redis / Memcached / PDO 存储与分布式并发控制。PHP 8.3+。

功能特性

• 五种限流算法：令牌桶（支持突发）、漏桶（抑制突发）、滑动窗口（精确日志）、滑动窗口计数器（加权近似、内存恒定）、固定窗口计数器。
• 组合限流：CompositeLimiter 将多条规则串联，全部通过才放行（两阶段：预检 + 提交回滚）。
• 多存储驱动：内存（单进程）、APCu（单机多进程）、Redis / Memcached / PDO（分布式，跨机器一致）。
• 并发控制：任务 / 进程 / Fiber 协程的本地与分布式并发上限，底层统一为共享槽位计数信号量。
• 分布式原子性：Redis Lua 脚本保证「读取→补充→扣减→写回」原子执行，支持单机 / Sentinel / Cluster。
• 声明式注解：#[RateLimit] 标注在控制器上，由框架中间件反射读取。
• 结构化结果：LimiterResult 携带剩余额度、重试等待、429 响应头，可直接接入各类框架。
• 配置驱动注册表：LimiterManager::fromConfig() 一份数组批量注册命名限流器，按名取用。
• 容灾降级：ResilientStore 装饰任意存储，Redis / PDO 宕机时按策略兜底（默认 fail-open 放行并标记降级），业务不被限流器拖垮。
• 事件回调：LimiterEventHandler 在每次决策后（onResult）与异常时（onError）回调，方便接入日志 / 指标 / 告警。
• 质量门禁：内置 PHPStan（level 6）静态分析，composer analyze 一键检查。
• PHP 8.3+：使用 #[\Override]、typed class constants、json_validate() 等新特性。

系统要求

• PHP >= 8.3
• 可选扩展（按所用存储驱动）：ext-redis、ext-apcu、ext-memcached、ext-pdo

安装

统一入口 Limiter（推荐）

Limiter 实例方法：allow() / check()（返回 LimiterResult）/ consume() / consumeOrFail()（超限抛 RateLimitExceededException）/ getRemaining() / getWaitTime() / reset() / getCapacity()；流式配置 withCapacity() / withRate() / withTtl() / withPrefix() / withStore() / withType() / withEventHandler()（均返回新实例，保持不可变）。

快速开始

本地限流（令牌桶）

组合限流

并发控制（共享槽位信号量）

v2.0 迁移提示：v1.x 的 TaskLimiter::create($max, $capacity, $rate)、ProcessLimiter::getInstance($max, $capacity, $rate)、new FiberLimiter($max, $capacity, $rate, $store) 已全部改为「共享槽位信号量」语义。并发上限现在真实生效，旧签名不再兼容。

分布式限流（跨机器）

声明式注解

配置驱动注册表 LimiterManager

用一份数组在框架引导阶段集中声明多条限流规则，运行期按业务名取用：

同名存储只构建一次并复用；store 字段可填存储名、存储配置数组或类型字符串。

容灾降级与事件回调

把任意存储包进 ResilientStore，底层（Redis / PDO 等）不可用时按策略兜底，业务不会被限流器拖垮：

降级结果会体现在 LimiterResult（额外携带 degraded / degradedReason）与响应头（X-RateLimit-Degraded: 1）上，便于观测。

事件回调（LimiterEventHandler）则在每次决策后 / 异常时触发，方便接入日志、指标与告警：

LimiterMiddleware 同样支持 withEventHandler()，并在降级时把 X-RateLimit-Degraded 写入响应头。

架构

API 速查

StoreInterface

RateLimiterInterface

LimiterResult

LimiterConfig

单元测试

测试覆盖全部核心功能，共 125 个测试用例、540 项断言（PHPUnit 10.5/11，PHP 8.3），全绿。

自定义存储

实现 StoreInterface 即可：

开发

从 v1.x 升级到 v2.0

• PHP：最低要求 >= 8.3（原为 8.2）。
• 并发限流器签名变更：TaskLimiter::create(int $maxConcurrency, ?StoreInterface $store = null, string $prefix = 'task:')、ProcessLimiter::getInstance(int $maxProcesses = 10, string $prefix = 'process:')、new FiberLimiter(int $maxFibers, StoreInterface $store = new MemoryStore(), string $prefix = 'fiber:')。并发上限现在真实生效。
• LimiterResult：旧版 $result->waitTime 更名为 retryAfter；构造时不再二次赋值 readonly 属性。
• RedisStore::eval()：已重命名为 evalScript(string $script, array $keys, array $args)，分布式限流现在真正生效（v1.x 的 ARGV 被丢弃从未生效）。
• Limiter::leakyBucket() / counter()：现在分别返回真正的漏桶与计数器（v1.x 一律返回令牌桶）。

从 v2.0 升级到 v2.1

v2.1.0 为向后兼容的增量版本（纯新增能力，未改动既有 API 行为）：

• 新增 LimiterManager：LimiterManager::fromConfig($array) 批量注册命名限流器，按名取用。
• 新增容灾降级：ResilientStore 装饰任意存储，底层故障时默认 fail-open 放行并标记 LimiterResult::$degraded，响应头增加 X-RateLimit-Degraded。FailurePolicy 提供 ALLOW / RETHROW 两种策略。
• 新增事件回调：LimiterEventHandler::onResult() / onError()，可通过 Limiter::withEventHandler() 与 LimiterMiddleware::withEventHandler() 绑定。
• 新增 RateLimiterInterface::getStore()：所有算法均实现（组合限流器返回首个子规则的存储），供中间件统一检测降级。
• 新增静态分析：内置 PHPStan（level 6），composer analyze 检查。

既有调用方式（v2.0）无需任何改动即可升级到 v2.1.0。

从 v2.1 升级到 v2.2

v2.2.0 为向后兼容的增量版本（新增可选参数，未改动既有 API 行为）：

• Limiter::redis() 新增 $prefix 参数：此前 STANDALONE 硬编码 'kode:limiting:'、SENTINEL/CLUSTER 省略 prefix（落回默认值）；现三种模式统一透传到 RedisStore。
• Limiter::memcached() 新增 $prefix 参数：此前签名无 prefix，MemcachedStore::create() 不传 prefix；现与 Redis/APCu 一致。
• storeFromArray() Redis 分支支持 sentinel/cluster：此前只走 standalone；现按 config['mode'] 路由三模式，各分支从 config 取 sentinels/masterName/clusterNodes/prefix 等键。

既有调用方式（v2.1）无需任何改动即可升级到 v2.2.0——所有新参数均带默认值 'kode:limiting:'。

许可证

Apache License 2.0 - 参见 LICENSE 文件