Download the PHP package harmlessprince/superban without Composer
On this page you can find all versions of the php package harmlessprince/superban. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download harmlessprince/superban
More information about harmlessprince/superban
Files in harmlessprince/superban
Package superban
Short Description Ban client completely for a period of time after they have exhausted there request
License MIT
Informations about the package superban
Superban Package
SuperBan is a Laravel middleware package that helps you manage and control the rate of incoming requests to your application. It can be useful in scenarios where you want to prevent abuse, limit the number of requests from a specific route or group of route the client and enforce temporary bans when necessary.
The package is designed using the Token Bucket Algorithm. Below is a brief explanation of the algorithm from Google `The token bucket is an algorithm used in packet-switched and telecommunications networks. It can be used to check that data transmissions, in the form of packets, conform to defined limits on bandwidth and burstiness (a measure of the unevenness or variations in the traffic flow). ` In the concept of this Superban package, below is a brief explanation of how it works. The middleware has a first parameter called maximumRequest. This maximum request parameter represents our tokens and is associated with a key in the cache. So each incoming request into our server consumes a token; if no tokens are left, the request is rejected. If the client tries to hit the same endpoint again within the interval specified for the token to be used, the client is then banned from the specific route for the duration of the ban time supplied. `Note: All supplied parameters are expected to be in minutes.`
Installation
Once the Superban package is installed, the package will be autoloaded, this package is built with php 8.1. Any Laravel version that supports PHP 8.1 will autoload the package; however, if you want to add it yourself.
Open up config/app.php
and add the following to the providers
key.
Configuration
The default cache driver is file
; you can change it to any laravel supported cache driver in your environment variable like below
You can publish the configuration file using this command:
A configuration-file named superban.php
with defaults will be placed in your config
directory:
Usage
To use the SuperBan middleware in your routes, you can apply it like any other middleware. For example, in your routes file or controller: You can customize the SuperBan behaviour by providing additional parameters:
- **Maximum Requests:** The maximum number of requests allowed in the specified interval (default: 200).
- **Interval in Minutes:** The time window (in minutes) during which the maximum requests are allowed (default: 2 minutes).
- **Ban Time in Minutes:** The duration (in minutes) a client is banned if they exceed the maximum requests (default: 1440 minutes or 24 hours).
Exceptions
- **`SuperBanClientBannedException`**: Thrown when a client is banned.
- **`SuperBanTooManyRequestException`**: Thrown when a client exceeds the maximum allowed requests.
- **`SuperBanInvalidMaxRequestParamException`**: This exception is thrown when the maximum requests parameter supplied method is either not a numeric value or is not a positive integer.
- **`SuperBanInvalidIntervalParamException`**: This exception is thrown when the interval parameter supplied method is either not a numeric value or is not a positive integer.
- **`SuperBanInvalidBanTimeParamException`**: This exception is thrown when the ban time parameter provided is either not a numeric value or is not a positive integer.
Extra
When you use the middlware in your route, the package adds some headers to every response going out of the application like below
The response header below implies the client has excided the maximum number of requests and can try again in 18 seconds.
Testing
Test Result Should Look Like This
Author
Name: Adewuyi Taofeeq
Email: [email protected]
LinkenIn: Adewuyi Taofeeq Olamikean
License
MIT