Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jaytaph/ratelimitbundle
Add rate limits to your controllers / actions easily through annotations
https://github.com/jaytaph/ratelimitbundle
Last synced: 3 days ago
JSON representation
Add rate limits to your controllers / actions easily through annotations
- Host: GitHub
- URL: https://github.com/jaytaph/ratelimitbundle
- Owner: jaytaph
- License: mit
- Created: 2014-05-24T19:15:52.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2023-09-11T08:16:55.000Z (over 1 year ago)
- Last Synced: 2024-12-14T01:05:53.271Z (10 days ago)
- Language: PHP
- Size: 755 KB
- Stars: 332
- Watchers: 17
- Forks: 75
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
NoxlogicRateLimitBundle
========================
[](https://travis-ci.org/jaytaph/RateLimitBundle)
[](https://scrutinizer-ci.com/g/jaytaph/RateLimitBundle/?branch=master)
[](https://scrutinizer-ci.com/g/jaytaph/RateLimitBundle/?branch=master)
[](https://packagist.org/packages/noxlogic/ratelimit-bundle) [](https://packagist.org/packages/noxlogic/ratelimit-bundle) [](https://packagist.org/packages/noxlogic/ratelimit-bundle) [](https://packagist.org/packages/noxlogic/ratelimit-bundle)
This bundle provides enables the `#[RateLimit()]` attribute which allows you to limit the number of connections to actions.
This is mostly useful in APIs.
The bundle is prepared to work by default in cooperation with the `FOSOAuthServerBundle`. It contains a listener that adds the OAuth token to the cache-key. However, you can create your own key generator to allow custom rate limiting based on the request. See *Create a custom key generator* below.
This bundle is partially inspired by a GitHub gist from Ruud Kamphuis: https://gist.github.com/ruudk/3350405
## Features
* Simple usage through attributes
* Customize rates per controller, action and even per HTTP method
* Multiple storage backends: Redis, Memcached and Doctrine cache
## Installation
Installation takes just few easy steps:
### Step 1: Install the bundle using composer
If you're not yet familiar with Composer see http://getcomposer.org.
Tell composer to download the bundle by running the command:
``` bash
composer require noxlogic/ratelimit-bundle
```
### Step 2: Enable the bundle
If you are using `symfony/flex` you can skip this step, the bundle will be enabled automatically,
otherwise you need to enable the bundle by adding it to the `bundles.php` file of your project.
``` php
['all' => true],
// ..
];
```
### Step 3: Install a storage engine
#### Redis
If you want to use Redis as your storage engine, you might want to install `SncRedisBundle`:
* https://github.com/snc/SncRedisBundle
#### Memcache
If you want to use Memcache, you might want to install `LswMemcacheBundle`
* https://github.com/LeaseWeb/LswMemcacheBundle
#### Doctrine cache
If you want to use Doctrine cache as your storage engine, you might want to install `DoctrineCacheBundle`:
* https://github.com/doctrine/DoctrineCacheBundle
Referer to their documentations for more details. You can change your storage engine with the `storage_engine` configuration parameter. See *Configuration reference*.
## Configuration
### Enable bundle only in production
If you wish to enable the bundle only in production environment (so you can test without worrying about limit in your development environments), you can use the `enabled` configuration setting to enable/disable the bundle completely. It's enabled by default:
```yaml
# config_dev.yml
noxlogic_rate_limit:
enabled: false
```
### Configuration reference
This is the default bundle configuration:
```yaml
noxlogic_rate_limit:
enabled: true
# The storage engine where all the rates will be stored
storage_engine: ~ # One of "redis"; "memcache"; "doctrine"; "php_redis"; "php_redis_cluster"
# The redis client to use for the redis storage engine
redis_client: default_client
# The Redis service, use this if you dont use SncRedisBundle and want to specify a service to use
# Should be instance of \Predis\Client
redis_service: null # Example: project.predis
# The Redis client to use for the php_redis storage engine
# Depending on storage_engine an instance of \Redis or \RedisCluster
php_redis_service: null # Example: project.redis
# The memcache client to use for the memcache storage engine
memcache_client: default
# The Memcached service, use this if you dont use LswMemcacheBundle and want to specify a service to use
# Should be instance of \Memcached
memcache_service: null # Example: project.memcached
# The Doctrine Cache provider to use for the doctrine storage engine
doctrine_provider: null # Example: my_apc_cache
# The Doctrine Cache service, use this if you dont use DoctrineCacheBundle and want to specify a service to use
# Should be an instance of \Doctrine\Common\Cache\Cache
doctrine_service: null # Example: project.my_apc_cache
# The HTTP status code to return when a client hits the rate limit
rate_response_code: 429
# Optional exception class that will be returned when a client hits the rate limit
rate_response_exception: null
# The HTTP message to return when a client hits the rate limit
rate_response_message: 'You exceeded the rate limit'
# Should the ratelimit headers be automatically added to the response?
display_headers: true
# What are the different header names to add
headers:
limit: X-RateLimit-Limit
remaining: X-RateLimit-Remaining
reset: X-RateLimit-Reset
# Rate limits for paths
path_limits:
path: ~ # Required
methods:
# Default:
- *
limit: ~ # Required
period: ~ # Required
# - { path: /api, limit: 1000, period: 3600 }
# - { path: /dashboard, limit: 100, period: 3600, methods: ['GET', 'POST']}
# Should the FOS OAuthServerBundle listener be enabled
fos_oauth_key_listener: true
```
## Usage
### Simple rate limiting
To enable rate limiting, you only need to add the attribute to the specified action
```php
generateKey();
$event->addToKey($key);
// $event->setKey($key); // to overwrite key completely
}
}
```
Make sure to generate a key based on what is rate limited in your controllers.
And example of a IP-based key generator can be:
```php
getRequest();
$event->addToKey($request->getClientIp());
}
}
```
## Throwing exceptions
Instead of returning a Response object when a rate limit has exceeded, it's also possible to throw an exception. This
allows you to easily handle the rate limit on another level, for instance by capturing the ``kernel.exception`` event.
## Running tests
If you want to run the tests use:
```
./vendor/bin/simple-phpunit
```