limitrr-php

Limitrr PHP は、私が NodeJS 用に作成した別のライブラリである Limitrr から非常に大きな影響を受けています。そちらはこちらで確認できます。

Limitrr PHP を使用すると、アプリケーションにレート制限を簡単に統合できます。他の類似パッケージとは異なり、このユーティリティはリクエスト数だけでなく完了したアクション数（例：一定期間内に正常に作成できるアカウント数）でも制限でき、しかもカスタムオプションで制限を設定できます。さらに、カスタムディスクリミネーターも使用できるため、ユーザーの IP だけで制限する必要はもうありません。

このライブラリは、SlimPHP プロジェクト内にある様々なルートを簡単にレート制限するためのミドルウェア機能も提供します。

このプロジェクトを気に入っていただけましたら、GitHub で 🌟 を付けてください。

プルリクエストを歓迎します

インストール

ターミナルで次のコマンドラインを実行すると、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 は制限対象となる識別子です（例：ディスクリミネーターごとの完了アクション数 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 は制限対象となる識別子です（例：ディスクリミネーターごとの完了アクション数 x）
• route: 文字列 どのルートに値を挿入しますか？ 設定しない場合は、default ルートからカウントを取得します。

特定のリクエスト/完了キーから値を削除する

limitrr->reset()

戻り値: ブール値

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

->reset() のパラメータ

関数には配列を介して渡す必要があります

• 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]);