Download the PHP package eddiejibson/limitrr-php without Composer

Light rate limting within PHP using Redis.

Limitrr PHP is very heavily inspired by my other library, Limitrr which was created for NodeJS. Check it out here

Limitrr PHP allows users to easily integrate rate limiting within their application. Unlike other similar packages, this utility allows the user to limit not only by the number of requests but also the number of completed actions (e.g allowing a certain amount of accounts to be successfully created within a timespan) and have such restricted with custom options. As well as this, custom discriminators are possible - you no longer have to limit by just the user's IP.

This library also provides a middleware function for easily ratelimting whatever various routes you may have within a SlimPHP project.

If you appreciate this project, please 🌟 it on GitHub.

Pull Requests are welcomed

Installation

You can install the limitrr-php libary via executing the following commandline in your terminal (assuming you have composer installed)

Quick Guide

Basic Usage

Get value of certain key

limitrr->get()

Returns: Array

->get() Parameters

Must be passed into the function via an array

• discriminator: Required Where discriminator is the thing being limited (e.g x amount of completed actions per discriminator)
• route: String What route should the values be retrieved from? If this is not set, it will get the counts from the default route
• type: String Instead of retrieving both values, you can specify either requests or completed in this key and only that will be returned as an integer.

->get() Examples

Complete action/task count

limitrr->complete()

Returns: Integer

->complete() Parameters

Must be passed into the function via an array

• discriminator: Required Where discriminator is the thing being limited (e.g x amount of completed actions per discriminator)
• route: String What route should the values be inserted into? If this is not set, it will get the counts from the default route

Removal of values from certain request/completed keys

limitrr->reset()

Returns: Boolean

->reset() Parameters

Must be passed into the function via an array

• discriminator: Required Where discriminator is the thing being limited (e.g x amount of completed actions per discriminator)
• route: String What route should the values be reset from? If this is not set, it will reset the counts from the default route
• type: String Which count do you wish to be reset? requests or completed? If this is not set, both will be removed.

Configuration

redis

Required: false

Type: Array OR String

Description: Redis connection information.

Either pass in a string containing the URI of the redis instance or an object containing the connection information:

• port: Integer Redis port. Defaults to: 6379
• host: String Redis hostname. Defaults to: "127.0.0.1"
• password: String Redis password. Defaults to: ""
• database: Integer Redis DB. Defaults to: 0

Example of the redis array/string that could be passed into Limitrr

options

Required: false

Type: Array

Description: Various options to do with Limitrr.

• keyName: String The keyname all of the requests will be stored under. This is mainly for aesthetic purposes and does not affect much. However, this should be changed on each initialization of the main class to prevent conflict. Defaults to: "limitrr"
• errorStatusCode: Integer Status code to return when the user is being rate limited. Defaults to 429 (Too Many Requests)

Example of the options object that could be passed into Limitrr

routes

Required: false

Type: Array

Description: Define route restrictions.

Inside the routes object, you can define many separate routes and set custom rules within them. The custom rules you can set are:

• requestsPerExpiry: Integer How many requests can be accepted until user is rate limited? Defaults to: 100
• completedActionsPerExpiry: Integer How many completed actions can be accepted until the user is rate limited? This is useful for certain actions such as registering a user - they can have a certain amount of requests but a different (obviously smaller) amount of "completed actions". So if users have recently been successfully registered multiple times under the same IP (or other discriminator), they can be rate limited. They may be allowed 100 requests per certain expiry for general validation and the like, but only a small fraction of that for intensive procedures. Defaults to the value in requestsPerExpiry or 5 if not set.
• expiry: Integer How long should the requests be stored (in seconds) before they are set back to 0? If set to -1, values will never expire and will stay that way indefinitely or must be manually removed. Defaults to: 900 (15 minutes)
• completedExpiry: Integer How long should the "completed actions" (such as the amount of users registered from a particular IP or other discriminator) be stored for (in seconds) before it is set back to 0? If set to -1, such values will never expire and will stay that way indefinitely or must be manually removed. Defaults to the value in expiry or 900 (15 minutes) if not set.
• errorMsgs: Object Seperate error messages for too many requests and too many completed actions. They have been given the respective key names "requests" and "actions". This will be returned to the user when they are being rate limited. If no string was set in requests, it will default to "As you have made too many requests, you are being rate limited.". Furthermore, if a value has not been set in completed, it will resolve to the string found in requests. Or, if that wasn't set either, "As you performed too many successful actions, you have been rate limited." will be it's value.

Example of the routes array