README

使用漏桶算法的无框架节流。

桶具有定义的容量和每分钟的漏出速率。桶还可以存储额外的任意数据。

• 许可证
• 作者
• 要求
• 安装
• 用法

许可证

此项目是开源的，可在MIT 许可证下使用。

作者

• Bayfront Media 主页
• Bayfront Media GitHub

要求

• PHP ^8.0
• PDO PHP 扩展
• JSON PHP 扩展

安装

composer require bayfrontmedia/leaky-bucket

用法

存储适配器

必须向 Bayfront\LeakyBucket\Bucket 构造函数传递一个 Bayfront\LeakyBucket\ApadpterInterface 实例。有各种存储适配器可用，每个适配器都有自己的配置要求。

Flysystem

Flysystem 适配器允许您使用 Flysystem League\Flysystem\Filesystem v3 实例进行桶存储。

use Bayfront\LeakyBucket\Adapters\Flysystem;

$adapter = new Flysystem($filesystem, '/root_path');

本地

Local 适配器允许您使用原生 PHP 在本地存储桶。

use Bayfront\LeakyBucket\Adapters\Local;

$adapter = new Local('/root_path');

PDO

PDO 适配器允许您使用 \PDO 实例将桶存储到数据库中。

PDO 适配器将创建/使用名为 "buckets" 的表，除非在构造函数中指定了其他名称。

use Bayfront\LeakyBucket\Adapters\PDO;

$adapter = new PDO($dbh, 'table_to_use');

使用 up 方法创建此适配器将使用的必要数据库表。使用 down 方法删除数据库表。

这些方法会抛出 Bayfront\LeakyBucket\AdapterException 异常。

try {

    $adapter->up();

} catch (AdapterException $e) {
    die($e->getMessage());
}

开始使用漏桶

一旦创建了适配器，就可以与漏桶一起使用。此外，还可以向构造函数传递一个可选的设置数组。默认设置如下所示。

use Bayfront\LeakyBucket\AdapterException;
use Bayfront\LeakyBucket\BucketException;
use Bayfront\LeakyBucket\Bucket;

// Create/retrieve a bucket with a given ID

try {

    $bucket = new Bucket('bucket_id', $adapter, [
        'capacity' => 10, // Total drop capacity
        'leak' => 10 // Number of drops to leak per minute
    ]);

} catch (AdapterException | BucketException $e) {
    die($e->getMessage());
}

// Work with the bucket

$bucket->leak();

if ($bucket->hasCapacity()) {

    try {

        $bucket->fill()->save();

    } catch (AdapterException $e) {
        die($e->getMessage());
    }

}

注意：在尝试对容量进行任何计算之前，请务必先 leak() 桶。此外，必须使用 save() 方法来存储当前的桶设置以供将来使用。

公共方法

• exists
• save
• get
• reset
• delete
• isFull
• getCapacity
• getCapacityUsed
• getCapacityRemaining
• hasCapacity
• getLeakPerSecond
• getSecondsPerDrop
• getSecondsUntilCapacity
• getSecondsUntilEmpty
• touch
• getLastTime
• fill
• leak
• spill
• overflow
• dump
• hasData
• setData
• getData
• forgetData

exists

描述

检查此桶 ID 是否已在存储中存在。

参数

• 无

返回

• (bool)

示例

if ($bucket->exists()) {
    // Do something
}

save

描述

保存桶。

参数

• 无

返回

• (self)

抛出

Bayfront\LeakyBucket\AdapterException

示例

try {

    $bucket->save();

} catch (AdapterException $e) {
    die($e->getMessage());
}

get

描述

返回整个桶的内容。

参数

• 无

返回

• (array)

示例

$contents = $bucket->get();

reset

描述

重置所有桶信息和数据。

参数

• 无

返回

• (self)

示例

$bucket->reset();

delete

描述

重置桶并删除存储中的文件。

参数

• 无

返回

• (self)

抛出

Bayfront\LeakyBucket\AdapterException

示例

try {

    $bucket->delete();

} catch (AdapterException $e) {
    die($e->getMessage());
}

isFull

描述

检查桶是否已满。

参数

• 无

返回

• (bool)

示例

if ($bucket->isFull()) {
    // Do something
}

getCapacity

描述

返回桶的总容量。

参数

• 无

返回

• (int)

示例

echo $bucket->getCapacity();

getCapacityUsed

描述

返回桶中的滴数。

参数

• 无

返回

• (float)

示例

echo $bucket->getCapacityUsed();

getCapacityRemaining

描述

返回剩余的桶容量。

参数

• 无

返回

• (float)

示例

echo $bucket->getCapacityRemaining();

hasCapacity

描述

检查桶是否有足够的空间填充指定的滴数。

参数

• $drops = 1 (int)

返回

• (bool)

示例

if ($bucket->hasCapacity(5)) {
    // Do something
}

getLeakPerSecond

描述

返回桶每秒泄漏的滴数。

参数

• 无

返回

• (float)

示例

echo $bucket->getLeakPerSecond();

getSecondsPerDrop

描述

返回泄漏一个滴所需的秒数。

参数

• 无

返回

• (float)

示例

echo $bucket->getSecondsPerDrop();

getSecondsUntilCapacity

描述

返回桶达到指定滴数容量所需的时间（秒）。如果桶已有容量，则返回 0。

参数

• $drops = 1 (int)

返回

• (float)

示例

echo $bucket->getSecondsPerDrop();

getSecondsUntilEmpty

描述

返回桶空所需的时间（秒）。

参数

• 无

返回

• (float)

示例

echo $bucket->getSecondsUntilEmpty();

touch

描述

手动更新桶的时间戳。

当调用以下任何一种方法时，水桶的时间戳会自动更新。

• fill
• leak
• spill
• dump

参数

• 无

返回

• (self)

示例

$bucket->touch();

getLastTime

描述

返回水桶的最后时间戳。

参数

• 无

返回

• (int)

示例

echo $bucket->getLastTime();

fill

描述

使用指定数量的滴填满水桶。

如果不允许溢出，且水桶没有所需容量，将抛出Bayfront\LeakyBucket\BucketException异常。否则，水桶将被允许溢出。

参数

• $drops = 1 (int)
• $allow_overflow = false (bool)

返回

• (self)

抛出

• Bayfront\LeakyBucket\BucketException

示例

try {
    
    $bucket->fill();
    
} catch (BucketException $e) {
    die($e->getMessage());
}

leak

描述

通过计算自上次时间戳以来要泄漏的滴数来更新水桶。

参数

• 无

返回

• (self)

示例

$bucket->leak();

spill

描述

从水桶中溢出指定数量的滴。

参数

• $drops = 1 (int)

返回

• (self)

示例

$bucket->spill(5);

overflow

描述

从水桶中丢弃（清空）超出其容量的所有滴。

参数

• 无

返回

• (self)

示例

$bucket->overflow();

dump

描述

从水桶中丢弃（清空）所有滴。

参数

• 无

返回

• (self)

示例

$bucket->dump();

hasData

描述

检查此水桶是否包含任何附加数据，或使用点表示法指定特定键。

参数

• $key = NULL (string|null): 如果 NULL，则检查是否存在任何附加数据

返回

• (bool)

示例

if ($bucket->hasData('client_id')) {
    // Do something
}

setData

描述

使用点表示法为此水桶设置附加数据。

参数

• $key (string)
• $value (mixed)

返回

• (self)

示例

$bucket->setData('client_id', 5);

getData

描述

以点表示法返回此水桶的附加数据键，或者在未找到时返回可选的默认值。

参数

• $key = NULL (string|null): 当 NULL 时，返回整个数据数组
• $default = NULL (mixed)

返回

• (mixed)

示例

$client_id = $bucket->getData('client_id');

forgetData

描述

移除此水桶的点表示法附加数据键。

参数

• $key = NULL (string|null): 当 NULL 时，移除整个数据数组

返回

• (self)

示例

$bucket->forgetData('client_id');