victorive / superban
Easily ban your API clients for a specified period of time.
Requires
- php: ^8.1
- illuminate/support: ^10.38
Requires (Dev)
- laravel/pint: ^1.13
- orchestra/testbench: ^8.18
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- phpunit/phpunit: ^10
This package is auto-updated.
Last update: 2025-04-08 23:05:10 UTC
README
Superban is a Laravel package designed to enable you ban API clients for a specified period. It allows you to easily limit the number of requests a client can execute within a certain time frame, and if they surpass this limit, they will be banned for the specified duration.
Installation
Install the package via composer using:
composer require victorive/superban
Next, publish the configuration file (config/superban.php)
with:
php artisan vendor:publish --tag="superban-config"
The published configuration file enables you to customize the SUPERBAN_CACHE_DRIVER
and SUPERBAN_BAN_CRITERIA
parameters
for rate-limiting operations. These settings can be modified in your .env file with your preferred values.
If you choose to use the "database" as your cache driver, remember to run php artisan cache:table
to create the necessary tables for the cache storage.
See the Cache docs for more info.
Configuration
- The
SUPERBAN_CACHE_DRIVER
parameter determines the cache driver used for Superban operations. Supported drivers include"array", "database", "file", "memcached", "redis", "dynamodb", and "octane".
- The
SUPERBAN_BAN_CRITERIA
parameter sets the criteria for rate-limiting or banning users. - Supported options include
"user_id", "email", and "ip"
.
Example configuration:
return [ /** * The cache driver to use for superban operations. * * Supported drivers: "array", "database", "file", * "memcached", "redis", "dynamodb", "octane" */ 'cache_driver' => env('SUPERBAN_CACHE_DRIVER', 'file'), /** * The ban criteria to use when rate-limiting/banning users. * * Supported options: "user_id", "email", "ip", */ 'ban_criteria' => env('SUPERBAN_BAN_CRITERIA', 'ip'), ];
Update your .env
file with your preferred values for the keys below:
SUPERBAN_CACHE_DRIVER= {{your preferred cache driver}}
SUPERBAN_BAN_CRITERIA= {{your preferred ban criteria}}
Usage
To utilize Superban's functionalities, add the following to your app/Http/Kernel.php
file.
protected $middlewareAliases = [ // ... 'superban' => \Victorive\Superban\Middleware\SuperbanMiddleware::class, ];
Then you can protect your routes using the middleware rules. For instance
- Route group:
Route::middleware(['superban:100,2,720'])->group(function () { Route::post('/someroute', function () { // ... }); Route::post('anotherroute', function () { // ... }); });
- Single route:
Route::post('/thisroute', function () { // ... })->middleware(['superban:100,2,720']);
In the examples above,
- 100 is the maximum number of requests allowed,
- 2 is the time period (in minutes) during which these requests can occur, and
- 720 is the duration (in minutes) for which the user will be banned after exceeding the limit.
Testing
To run the tests, use the following command:
vendor/bin/phpunit
Changelog
For information on recent updates, refer to the CHANGELOG file.
Contributing
Contributions are welcome! Feel free to fork the repo, make any changes or report any issues, and submit a PR.
License
This package is licensed under the MIT License. For more information, please see the License File.