hamburgscleanest/laravel-guzzle-throttle

A Laravel wrapper for https://github.com/hamburgscleanest/guzzle-advanced-throttle.

This package's canonical repository appears to be gone and the package has been frozen as a result.

v5.0.0 2021-09-21 19:18 UTC

Requires

• php: ^8.0
• hamburgscleanest/guzzle-advanced-throttle: ^5.0.1
• illuminate/support: ^8

Requires (Dev)

• mockery/mockery: ^1
• orchestra/testbench: ^6
• phpunit/phpunit: ^9

MIT

• Timo

• api
• cache
• Guzzle
• response
• throttle
• rate limiting
• rate limit
• request
• laravel
• advanced
• wildcard
• wildcards
• ratelimit
• hamburgscleanest

README

A Laravel (>= 8.0) wrapper for Guzzle Advanced Throttle.

Install

Via Composer

composer require hamburgscleanest/laravel-guzzle-throttle

Automatic Package Discovery

Everything is automatically registered for you.

Configuration

Publish the config to get the example configuration.

php artisan vendor:publish

Example configuration

20 requests every 1 seconds

100 requests every 2 minutes

    return [
        'cache' => [
            // Name of the configured driver in the Laravel cache config file / Also needs to be set when "no-cache" is set! Because it's used for the internal timers
            'driver'   => 'default',
            // Cache strategy: no-cache, cache, force-cache
            'strategy' => 'cache',
            // TTL in minutes
            'ttl'      => 900,
            // When this is set to false, empty responses won't be cached.
            'allow_empty' => true
        ],
        'rules' => [
            // host (including scheme)
            'https://www.google.com' => [
                [
                    // maximum number of requests in the given interval
                    'max_requests'     => 20,
                    // interval in seconds till the limit is reset
                    'request_interval' => 1
                ],
                [
                // maximum number of requests in the given interval
                'max_requests'     => 100,
                // interval in seconds till the limit is reset
                'request_interval' => 120
                ]
            ]
        ]
    ];

Usage

To use the pre-configured client, you have to instantiate your client like this:

// returns an instance of GuzzleHttp\Client
$client = LaravelGuzzleThrottle::client(['base_uri' => 'https://www.google.com']);

After that, you can use all of the usual GuzzleHttp\Client methods, e.g.

$client->get('/test'));

Add other middlewares

You can still add other middlewares to the stack, too.
Define your stack as usual and then pass it to the throttled client:

$stack = HandlerStack::create(new CurlHandler());
$stack->push(some_other_middleware);

$client = LaravelGuzzleThrottle::client(['base_uri' => 'https://www.google.com', 'handler' => $stack]);

The client will 'automatically' add every other middleware to the top of the stack.

Caching

Beforehand

Responses with an error status code 4xx or 5xx are not cached (even with force-cache enabled)! Note: Also, 3xx redirect codes are not cached.

Supported drivers

The following drivers are officially supported: File, Redis and Memcached.

The configuration for the drivers can be seen in the middleware repository.

Options

Without caching - no-cache

Just throttle the requests and don't cache them. When the limit is exceeded, a 429 - Too Many Requests exception is thrown.

With caching (default) - cache

Use cached responses when your defined rate limit is exceeded. The middleware tries to fall back to a cached response before throwing a 429 - Too Many Requests exception.

With forced caching - force-cache

Always uses the cached responses when available to spare your rate limits. It only sends the request when it is not cached. If there is no cached response and the request limits are exceeded, it falls back to throwing a 429 - Too Many Requests exception.

Wildcards

If you want to define the same rules for multiple different hosts, you can use wildcards. A possible use case can be subdomains:

$rules = new RequestLimitRuleset([
        'https://www.{subdomain}.mysite.com' => [
            [
                'max_requests'     => 50,
                'request_interval' => 2
            ]
        ]
    ]);

This host matches https://www.en.mysite.com, https://www.de.mysite.com, https://www.fr.mysite.com, etc.

Further details

If you want to know more about the possible configurations, head over to the middleware repository: Guzzle Advanced Throttle.

Changes

Please see CHANGELOG for more information on what has changed recently.

Testing

composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Timo Prüße
• Andre Biel
• All Contributors

License

The MIT License (MIT). Please see License File for more information.