limitrr-php

Limitrr PHP 在很大程度上受到了我为 NodeJS 创建的另一个库 Limitrr 的启发。点击这里查看。

Limitrr PHP 允许用户轻松地在应用中集成速率限制。与其他类似的包不同，该工具不仅允许用户按请求数量进行限制，还可以按已完成操作的数量进行限制（例如允许在一个时间段内成功创建一定数量的账户），并可配合自定义选项对其进行限制。此外，它还支持自定义标识符——你不再需要仅根据用户 IP 进行限制。

该库还提供了一个中间件函数，可让你轻松地对 SlimPHP 项目中可能存在的各种路由进行限流。

如果你喜欢这个项目，请在 GitHub 上为它点亮 🌟。

欢迎提交 Pull Request

安装

你可以通过在终端中执行以下命令行来安装 limitrr-php 库（假设你已经安装了 Composer）：

composer require eddiejibson/limitrr-php "^1.0"

快速指南

基本用法

require "/vendor/autoload.php"; //Require composer's autoload

$options = [
    //Redis keystore information
    "redis" => [
        "host" => "666.chae.sh",
        "port" => 6379,
        "password" => "supersecret",
    ],
    "routes" => [
        "default" => [
            "requestsPerExpiry" => 5,
        ],
    ],

];

//Initialize the Limitrr class and pass the options defined above into it
//Note that the options are not required.
$limitrr = new \eddiejibson\limitrr\Limitrr($options);

//Various examples like this can be found further into the documentation,
//for each function.
$result = $limitrr->get(["discriminator" => $ip]);
echo $result["requests"] + " Requests";
echo $result["completed"] + " Completed";
//Note that this library is no means just for SlimPHP, it just happens to
//provide a middleware function for those who may need it.

//Usage within SlimPHP
$app = new Slim\App();

//Use the Limitrr SlimPHP middleware function, if you wish:
$app->add(new \eddiejibson\limitrr\RateLimitMiddleware($limitrr)); //Make sure to pass in the main Limitrr
//instance we defined above into the middleware function. This is mandatory.

//You can also add the get IP middleware function, it will append the user's real IP
//(behind Cloudflare or not) to the request.
$app->add(new \eddiejibson\limitrr\getIpMiddleware());

//Example usage within a route
$app->get("/hello/{name}", function ($request, $response, $args) {
    $name = $args["name"];
    $ip = $request->getAttribute('realip'); //Get the IP that was defined within Limitrr's get IP middleware function
    return $response->getBody()->write("Hello, ${name}. Your IP is ${ip}.");
});

//You do not have to app the middleware function to every single route, globally.
//You can do it indivually, too - along with passing options into such. Like so:
$app->get("/createUser/{name}", function ($request, $response, $args) {
    //Non intensive actions like simple verification will have a different limit to intensive ones.
    //and will only be measured in terms of each request via the middleware.
    //No further action is required.
    if (strlen($args["name"]) < 5) {
        //Dummy function creating user
        $res = $someRandomClass->registerUser();
        if ($res) {
            //Intensive actions like actually registering a user should have a
            //different limit to normal requests, hence the completedActionsPerExpiry option.
            //and should only be added to once this task has been completed fully
            //In this example, we will be limiting the amount of completed actions a certain IP can make.
            //Anything can be passed in here, however. For example, a email address or user ID.
            //$request->getAttribute('realip') was determined by calling the middleware earlier - getIpMiddleware()
            $limitrr->complete(["discriminator"] => $ip);
        }
    }
})->add(new \eddiejibson\limitrr\RateLimitMiddleware($limitrr, ["route"=>"createUser"]));
//You can also pass the route name within the limitrr middleware function

$app->run();

获取指定键的值

limitrr->get()

返回： 数组

$limitrr->get([
    "discriminator" => $discriminator, //Required
    "route" => $route, //Not required, default is assumed
    "type" => $type //Not required
]);

->get() 参数

必须通过数组传递给函数

• discriminator: 必填 discriminator 是被限制的对象（例如每个 discriminator 允许完成的 X 个操作）
• route：字符串 应该从哪个路由检索值？如果未设置，将从 default 路由获取计数
• type：字符串 如果不想同时检索两个值，可以在此键中指定 requests 或 completed，此时仅返回对应的整数值

->get() 示例

$limitrr->get([
    "discriminator" => $discriminator,
    "type" => $type,
    "route" => $route
]); //Besides discriminator, all parameters are optional.
//If type is not passed into the function, it will
//return both the amount of requests and completed actions

//Where discriminator is the thing being limited
//e.g x amount of completed actions/requests per discriminator
$limitrr->get(["discriminator" => $discriminator]);

//This tends to be the user's IP.
$limitrr->get(["discriminator" => $ip]);
//This will return both the amount of requests and completed actions stored under the
//discriminator provided in an object. You can handle like this:
$result = $limitrr->get(["discriminator" => $ip]);
echo $result["requests"] + " Requests";
echo $result["completed"] + " Completed";

//The above example would get the request and completed task count from the default
//route. If you would like to retrieve values from a different route, you can specify
//this as well. It can be done like this:
$result = $limitrr->get(["discriminator" => $ip, "route" => "exampleRouteName"]);
echo $result["requests"] . " Requests made through the route exampleRouteName";
echo $result["completed"] . " Completed Tasks made through the route exampleRouteName";

//You may also only fetch only one type of value - instead of both requests and completed.
$result = $limitrr->get(["discriminator" => $ip, "route" => "exampleRouteName", "type" => "completed"]);
echo $result["completed"] . " Completed tasks made through the route exampleRouteName";

完成操作/任务计数

limitrr->complete()

返回： 整数

$limitrr->get([
    "discriminator" => $discriminator, //Required
    "route" => $route, //Not required, default is assumed
]);

->complete() 参数

必须通过数组传递给函数

• discriminator: 必填 discriminator 是被限制的对象（例如每个 discriminator 允许完成的 X 个操作）
• route：字符串 值应插入到哪个路由？如果未设置，将从 default 路由获取计数

删除特定请求/已完成操作键中的值

limitrr->reset()

返回： 布尔值

$limitrr->reset([
    "discriminator" => $discriminator, //Required
    "route" => $route, //Not required, default is assumed,
    "type" => $type //Not required
]);

->reset() 参数

必须通过数组传递给函数

• discriminator: 必填 discriminator 是被限制的对象（例如每个 discriminator 允许完成的 X 个操作）
• route：字符串 应从哪个路由重置值？如果未设置，将从 default 路由重置计数
• type：字符串 你希望重置哪个计数？requests 还是 completed？如果未设置，则两者都会被移除

//Where discriminator is the thing being limited
//e.g x amount of completed actions/requests per discriminator
//This will remove both the amount of requests and completed action count
$limitrr->reset(["discriminator" => $discriminator]);

//This tends to be the user's IP.
$limitrr->reset(["discriminator" => $ip]);