├── src
    ├── Time
    │   ├── TimerInterface.php
    │   └── MicrotimeTimer.php
    ├── Policy
    │   ├── LimitAlways.php
    │   ├── LimitPerIp.php
    │   ├── LimitCallback.php
    │   └── LimitPolicyInterface.php
    ├── CounterInterface.php
    ├── Storage
    │   ├── SimpleCacheStorage.php
    │   ├── ApcuStorage.php
    │   └── StorageInterface.php
    ├── CounterState.php
    ├── LimitRequestsMiddleware.php
    └── Counter.php
├── .phpunit-watcher.yml
├── composer-require-checker.json
├── infection.json.dist
├── psalm.xml
├── rector.php
├── UPGRADE.md
├── CHANGELOG.md
├── LICENSE.md
├── .styleci.yml
├── composer.json
└── README.md


/src/Time/TimerInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Time;
 6 | 
 7 | interface TimerInterface
 8 | {
 9 |     public function nowInMilliseconds(): float;
10 | }
11 | 


--------------------------------------------------------------------------------
/.phpunit-watcher.yml:
--------------------------------------------------------------------------------
 1 | watch:
 2 |     directories:
 3 |         - src
 4 |         - tests
 5 |     fileMask: '*.php'
 6 | notifications:
 7 |     passingTests: false
 8 |     failingTests: false
 9 | phpunit:
10 |     binaryPath: vendor/bin/phpunit
11 |     timeout: 180
12 | 


--------------------------------------------------------------------------------
/composer-require-checker.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "symbol-whitelist": [],
 3 |     "php-core-extensions": [
 4 |         "Core",
 5 |         "date",
 6 |         "json",
 7 |         "pcre",
 8 |         "Phar",
 9 |         "Reflection",
10 |         "SPL",
11 |         "standard",
12 |         "apcu"
13 |     ],
14 |     "scan-files": []
15 | }
16 | 


--------------------------------------------------------------------------------
/infection.json.dist:
--------------------------------------------------------------------------------
 1 | {
 2 |     "source": {
 3 |         "directories": [
 4 |             "src"
 5 |         ]
 6 |     },
 7 |     "logs": {
 8 |         "text": "php:\/\/stderr",
 9 |         "stryker": {
10 |             "report": "master"
11 |         }
12 |     },
13 |     "mutators": {
14 |         "@default": true
15 |     }
16 | }
17 | 


--------------------------------------------------------------------------------
/src/Time/MicrotimeTimer.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Time;
 6 | 
 7 | final class MicrotimeTimer implements TimerInterface
 8 | {
 9 |     private const MILLISECONDS_PER_SECOND = 1000;
10 | 
11 |     public function nowInMilliseconds(): float
12 |     {
13 |         return round(microtime(true) * self::MILLISECONDS_PER_SECOND);
14 |     }
15 | }
16 | 


--------------------------------------------------------------------------------
/src/Policy/LimitAlways.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Policy;
 6 | 
 7 | use Psr\Http\Message\ServerRequestInterface;
 8 | 
 9 | final class LimitAlways implements LimitPolicyInterface
10 | {
11 |     public function fingerprint(ServerRequestInterface $request): string
12 |     {
13 |         return sha1(strtolower($request->getMethod() . $request->getUri()->getPath()));
14 |     }
15 | }
16 | 


--------------------------------------------------------------------------------
/psalm.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0"?>
 2 | <psalm
 3 |     errorLevel="1"
 4 |     findUnusedBaselineEntry="true"
 5 |     findUnusedCode="false"
 6 |     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 7 |     xmlns="https://getpsalm.org/schema/config"
 8 |     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
 9 | >
10 |     <projectFiles>
11 |         <directory name="src" />
12 |         <ignoreFiles>
13 |             <directory name="vendor" />
14 |         </ignoreFiles>
15 |     </projectFiles>
16 |     <issueHandlers>
17 |         <MixedAssignment errorLevel="suppress" />
18 |     </issueHandlers>
19 | </psalm>
20 | 


--------------------------------------------------------------------------------
/src/Policy/LimitPerIp.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Policy;
 6 | 
 7 | use Psr\Http\Message\ServerRequestInterface;
 8 | 
 9 | final class LimitPerIp implements LimitPolicyInterface
10 | {
11 |     public function fingerprint(ServerRequestInterface $request): string
12 |     {
13 |         return sha1(strtolower($request->getMethod() . $request->getUri()->getPath() . $this->getIp($request)));
14 |     }
15 | 
16 |     private function getIp(ServerRequestInterface $request): string
17 |     {
18 |         /** @psalm-var array{REMOTE_ADDR?: string} $server */
19 |         $server = $request->getServerParams();
20 | 
21 |         return $server['REMOTE_ADDR'] ?? '';
22 |     }
23 | }
24 | 


--------------------------------------------------------------------------------
/src/Policy/LimitCallback.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Policy;
 6 | 
 7 | use Closure;
 8 | use Psr\Http\Message\ServerRequestInterface;
 9 | 
10 | final class LimitCallback implements LimitPolicyInterface
11 | {
12 |     /**
13 |      * @psalm-param Closure(ServerRequestInterface) $receiver
14 |      */
15 |     public function __construct(private Closure $receiver)
16 |     {
17 |     }
18 | 
19 |     public function fingerprint(ServerRequestInterface $request): string
20 |     {
21 |         $id = ($this->receiver)($request);
22 | 
23 |         if (!is_string($id) || '' === $id) {
24 |             throw new \InvalidArgumentException('The id must be a non-empty-string.');
25 |         }
26 | 
27 |         return $id;
28 |     }
29 | }
30 | 


--------------------------------------------------------------------------------
/rector.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | use Rector\CodeQuality\Rector\Class_\InlineConstructorDefaultToPropertyRector;
 6 | use Rector\Config\RectorConfig;
 7 | use Rector\Php74\Rector\Closure\ClosureToArrowFunctionRector;
 8 | use Rector\Set\ValueObject\LevelSetList;
 9 | 
10 | return static function (RectorConfig $rectorConfig): void {
11 |     $rectorConfig->paths([
12 |         __DIR__ . '/src',
13 |         __DIR__ . '/tests',
14 |     ]);
15 | 
16 |     // register a single rule
17 |     $rectorConfig->rule(InlineConstructorDefaultToPropertyRector::class);
18 | 
19 |     // define sets of rules
20 |     $rectorConfig->sets([
21 |         LevelSetList::UP_TO_PHP_80,
22 |     ]);
23 | 
24 |     $rectorConfig->skip([
25 |         ClosureToArrowFunctionRector::class,
26 |     ]);
27 | };
28 | 


--------------------------------------------------------------------------------
/src/CounterInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter;
 6 | 
 7 | /**
 8 |  * CounterInterface implementations describe the limiting algorithm. On each {@see CounterInterface::hit()} call
 9 |  * it determines when the next hit won't be limited.
10 |  */
11 | interface CounterInterface
12 | {
13 |     /**
14 |      * Determines when the next hit won't be limited. Should be called on each request.
15 |      *
16 |      * @param string $id Counter ID. Counters with distinct IDs do not affect each other.
17 |      * For example, using a current user ID will limit for the current user and using IP will limit by IP.
18 |      *
19 |      * @return CounterState Information about when the next hit won't be limited.
20 |      */
21 |     public function hit(string $id): CounterState;
22 | }
23 | 


--------------------------------------------------------------------------------
/src/Storage/SimpleCacheStorage.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Storage;
 6 | 
 7 | use Psr\SimpleCache\CacheInterface;
 8 | 
 9 | use function is_float;
10 | use function is_int;
11 | 
12 | final class SimpleCacheStorage implements StorageInterface
13 | {
14 |     public function __construct(private CacheInterface $cache)
15 |     {
16 |     }
17 | 
18 |     public function saveIfNotExists(string $key, float $value, int $ttl): bool
19 |     {
20 |         return $this->cache->set($key, $value, $ttl);
21 |     }
22 | 
23 |     public function saveCompareAndSwap(string $key, float $oldValue, float $newValue, int $ttl): bool
24 |     {
25 |         return $this->cache->set($key, $newValue, $ttl);
26 |     }
27 | 
28 |     public function get(string $key): ?float
29 |     {
30 |         /** @psalm-suppress MixedAssignment */
31 |         $value = $this->cache->get($key);
32 | 
33 |         return (is_int($value) || is_float($value)) ? (float) $value : null;
34 |     }
35 | }
36 | 


--------------------------------------------------------------------------------
/UPGRADE.md:
--------------------------------------------------------------------------------
 1 | # Upgrading Instructions for Yii Rate Limiter Middleware
 2 | 
 3 | This file contains the upgrade notes. These notes highlight changes that could break your
 4 | application when you upgrade the package from one version to another.
 5 | 
 6 | > **Important!** The following upgrading instructions are cumulative. That is, if you want
 7 | > to upgrade from version A to version C and there is version B between A and C, you need
 8 | > to following the instructions for both A and B.
 9 | 
10 | ## Upgrade from 1.x
11 | 
12 | In order to switch from version 1 to version 2 you need to update initialization code: 
13 | 
14 | ```php
15 | $cache = new ArrayCache();
16 | $counter = new Counter(2, 5, $cache);
17 | $middleware = new Middleware($counter, $responseFactory);
18 | ```
19 | 
20 | to
21 | 
22 | ```php
23 | $storage = new SimpleCacheStorage($cache);
24 | $counter = new Counter($storage, 2, 5);
25 | $middleware = new LimitRequestsMiddleware($counter, $responseFactory);
26 | ```
27 | 
28 | Check the readme for new features introduced in version 2.
29 | 


--------------------------------------------------------------------------------
/src/Policy/LimitPolicyInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Policy;
 6 | 
 7 | use Psr\Http\Message\ServerRequestInterface;
 8 | 
 9 | /**
10 |  * Defines policy for limiting requests i.e. which requests should be hit-counted together and which should be
11 |  * counted separately.
12 |  *
13 |  * For example, a user ID-based fingerprint will make rate limiting apply to current user requests only. An API
14 |  * token-based fingerprint will make rate limiting to apply to all requests with the same token.
15 |  */
16 | interface LimitPolicyInterface
17 | {
18 |     /**
19 |      * Returns request fingerprint. Two requests with the same fingerprint increase request counter. Requests
20 |      * with different fingerprints are counted and limited separately.
21 |      *
22 |      * @param ServerRequestInterface $request Request to get fingerprint for.
23 |      *
24 |      * @return string A fingerprint based on the request information.
25 |      */
26 |     public function fingerprint(ServerRequestInterface $request): string;
27 | }
28 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Yii Rate Limiter Change Log
 2 | 
 3 | ## 3.0.1 under development
 4 | 
 5 | - no changes in this release.
 6 | 
 7 | ## 3.0.0 July 26, 2023
 8 | 
 9 | - New #43: Add APCu counters storage (@jiaweipan)
10 | - Chg #21: Update `yiisoft/http` dependency (@devanych)
11 | - Chg #31: Raise `yiisoft/cache` dependency version to `^3.0` (@samdark)
12 | - Chg #34: Raise `psr/http-message` dependency version to `^1.1|^2.0` (@samdark)
13 | - Enh #25: Raise minimum `PHP` version to `8.0` (@terabytesoftw)
14 | - Enh #26: Add `psr/simple-cache` dependency version `^3.0` support (@vjik)
15 | - Enh #41: Adapt package to concurrent requests, for this `StorageInterface` method `save()` split to
16 |   `saveIfNotExists()` and `saveCompareAndSwap()` (@jiaweipan)
17 | 
18 | ## 2.0.0 August 15, 2021
19 | 
20 | - Enh #19: Introduce `LimitPolicyInterface`, `StorageInterface`, `TimerInterface`. Rename `Middleware` to
21 |   `LimitRequestsMiddleware` (@kafkiansky, @samdark)
22 | 
23 | ## 1.0.1 June 08, 2021
24 | 
25 | - Bug #14: Throw exception on call `getCacheKey()` in counter without the specified ID (@vjik)
26 | 
27 | ## 1.0.0 June 07, 2021
28 | 
29 | - Initial release.
30 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
 2 | All rights reserved.
 3 | 
 4 | Redistribution and use in source and binary forms, with or without
 5 | modification, are permitted provided that the following conditions
 6 | are met:
 7 | 
 8 |  * Redistributions of source code must retain the above copyright
 9 |    notice, this list of conditions and the following disclaimer.
10 |  * Redistributions in binary form must reproduce the above copyright
11 |    notice, this list of conditions and the following disclaimer in
12 |    the documentation and/or other materials provided with the
13 |    distribution.
14 |  * Neither the name of Yii Software nor the names of its
15 |    contributors may be used to endorse or promote products derived
16 |    from this software without specific prior written permission.
17 | 
18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21 | FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22 | COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
24 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
28 | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 | POSSIBILITY OF SUCH DAMAGE.
30 | 


--------------------------------------------------------------------------------
/src/Storage/ApcuStorage.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Storage;
 6 | 
 7 | use function is_float;
 8 | use function is_int;
 9 | 
10 | /**
11 |  * To use this storage, the [APCu PHP extension](https://www.php.net/apcu) must be loaded,
12 |  * And you should add "apc.enabled = 1" to your php.ini.
13 |  * In order to enable APCu for CLI you should add "apc.enable_cli = 1" to your php.ini.
14 |  */
15 | final class ApcuStorage implements StorageInterface
16 | {
17 |     private const DEFAULT_FIX_PRECISION_RATE = 1000;
18 | 
19 |     /**
20 |      * Apcu_cas of ACPu does not support float,  and yet supports int.
21 |      * APCu's stored value multiply by $fixPrecisionRate converts to int,
22 |      * AND the getter's value divide by $fixPrecisionRate converts to float.
23 |      * So use it to improve precision.
24 |      */
25 |     public function __construct(
26 |         private int $fixPrecisionRate = self::DEFAULT_FIX_PRECISION_RATE
27 |     ) {
28 |     }
29 | 
30 |     public function saveIfNotExists(string $key, float $value, int $ttl): bool
31 |     {
32 |         $value *= $this->fixPrecisionRate;
33 | 
34 |         return apcu_add($key, (int) $value, $ttl);
35 |     }
36 | 
37 |     public function saveCompareAndSwap(string $key, float $oldValue, float $newValue, int $ttl): bool
38 |     {
39 |         $oldValue *= $this->fixPrecisionRate;
40 |         $newValue *= $this->fixPrecisionRate;
41 | 
42 |         return apcu_cas($key, (int) $oldValue, (int) $newValue);
43 |     }
44 | 
45 |     public function get(string $key): ?float
46 |     {
47 |         /** @psalm-suppress MixedAssignment */
48 |         $value = apcu_fetch($key);
49 | 
50 |         return (is_int($value) || is_float($value))
51 |             ? (float) $value / $this->fixPrecisionRate
52 |             : null;
53 |     }
54 | }
55 | 


--------------------------------------------------------------------------------
/src/CounterState.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter;
 6 | 
 7 | /**
 8 |  * Rate limiter counter state stores information about when the next request won't be limited.
 9 |  */
10 | final class CounterState
11 | {
12 |     /**
13 |      * @param int $limit The maximum number of requests allowed with a time period.
14 |      * @param int $remaining The number of remaining requests in the current time period.
15 |      * @param int $resetTime Timestamp to wait until the rate limit resets.
16 |      * @param bool $isFailStoreUpdatedData If fail to store updated the rate limit data.
17 |      */
18 |     public function __construct(
19 |         private int $limit,
20 |         private int $remaining,
21 |         private int $resetTime,
22 |         private bool $isFailStoreUpdatedData = false
23 |     ) {
24 |     }
25 | 
26 |     /**
27 |      * @return int The maximum number of requests allowed with a time period.
28 |      */
29 |     public function getLimit(): int
30 |     {
31 |         return $this->limit;
32 |     }
33 | 
34 |     /**
35 |      * @return int The number of remaining requests in the current time period.
36 |      */
37 |     public function getRemaining(): int
38 |     {
39 |         return $this->remaining;
40 |     }
41 | 
42 |     /**
43 |      * @return int Timestamp to wait until the rate limit resets.
44 |      */
45 |     public function getResetTime(): int
46 |     {
47 |         return $this->resetTime;
48 |     }
49 | 
50 |     /**
51 |      * @return bool If requests limit is reached.
52 |      */
53 |     public function isLimitReached(): bool
54 |     {
55 |         return $this->remaining === 0;
56 |     }
57 | 
58 |     /**
59 |      * @return bool If fail to store updated the rate limit data.
60 |      */
61 |     public function isFailStoreUpdatedData(): bool
62 |     {
63 |         return $this->isFailStoreUpdatedData;
64 |     }
65 | }
66 | 


--------------------------------------------------------------------------------
/src/Storage/StorageInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter\Storage;
 6 | 
 7 | /**
 8 |  * Counter storage.
 9 |  */
10 | interface StorageInterface
11 | {
12 |     /**
13 |      * Saves the value of key only if it was not already saved in the store.
14 |      * It returns `false` if a value was saved. Otherwise, it returns `true`
15 |      * and saves the value.
16 |      * If the storage supports expiring keys, the key will expire after the provided TTL.
17 |      *
18 |      * @param string $key The ID of the counter to store.
19 |      * @param float $value The value of the counter.
20 |      * @param int $ttl The TTL value of this counter.
21 |      * @return bool
22 |      */
23 |     public function saveIfNotExists(string $key, float $value, int $ttl): bool;
24 | 
25 |     /**
26 |      * Compares the old value of key to the value which was saved in the store.
27 |      * If it matches, method saves it to the new value and returns `true`.
28 |      * Otherwise, it returns `false`.
29 |      * If the key does not exist in the storage, it returns `false`.
30 |      * If the storage supports expiring keys, the key will expire after the provided TTL.
31 |      *
32 |      * @param string $key The ID of the counter to store.
33 |      * @param float $oldValue The old value of the counter.
34 |      * @param float $newValue The new value of the counter.
35 |      * @param int $ttl The TTL value of this counter.
36 |      * @return bool
37 |      */
38 |     public function saveCompareAndSwap(string $key, float $oldValue, float $newValue, int $ttl): bool;
39 | 
40 |     /**
41 |      * Fetches a counter value from the storage.
42 |      *
43 |      * @param string $key The unique key of this counter in the storage.
44 |      *
45 |      * @return ?float It returns `float` if a value was saved. Otherwise, it returns `null`
46 |      */
47 |     public function get(string $key): ?float;
48 | }
49 | 


--------------------------------------------------------------------------------
/.styleci.yml:
--------------------------------------------------------------------------------
 1 | preset: psr12
 2 | risky: true
 3 | 
 4 | version: 8.1
 5 | 
 6 | finder:
 7 |   exclude:
 8 |     - docs
 9 |     - vendor
10 | 
11 | enabled:
12 |   - alpha_ordered_traits
13 |   - array_indentation
14 |   - array_push
15 |   - combine_consecutive_issets
16 |   - combine_consecutive_unsets
17 |   - combine_nested_dirname
18 |   - declare_strict_types
19 |   - dir_constant
20 |   - fully_qualified_strict_types
21 |   - function_to_constant
22 |   - hash_to_slash_comment
23 |   - is_null
24 |   - logical_operators
25 |   - magic_constant_casing
26 |   - magic_method_casing
27 |   - method_separation
28 |   - modernize_types_casting
29 |   - native_function_casing
30 |   - native_function_type_declaration_casing
31 |   - no_alias_functions
32 |   - no_empty_comment
33 |   - no_empty_phpdoc
34 |   - no_empty_statement
35 |   - no_extra_block_blank_lines
36 |   - no_short_bool_cast
37 |   - no_superfluous_elseif
38 |   - no_unneeded_control_parentheses
39 |   - no_unneeded_curly_braces
40 |   - no_unneeded_final_method
41 |   - no_unset_cast
42 |   - no_unused_imports
43 |   - no_unused_lambda_imports
44 |   - no_useless_else
45 |   - no_useless_return
46 |   - normalize_index_brace
47 |   - php_unit_dedicate_assert
48 |   - php_unit_dedicate_assert_internal_type
49 |   - php_unit_expectation
50 |   - php_unit_mock
51 |   - php_unit_mock_short_will_return
52 |   - php_unit_namespaced
53 |   - php_unit_no_expectation_annotation
54 |   - phpdoc_no_empty_return
55 |   - phpdoc_no_useless_inheritdoc
56 |   - phpdoc_order
57 |   - phpdoc_property
58 |   - phpdoc_scalar
59 |   - phpdoc_singular_inheritdoc
60 |   - phpdoc_trim
61 |   - phpdoc_trim_consecutive_blank_line_separation
62 |   - phpdoc_type_to_var
63 |   - phpdoc_types
64 |   - phpdoc_types_order
65 |   - print_to_echo
66 |   - regular_callable_call
67 |   - return_assignment
68 |   - self_accessor
69 |   - self_static_accessor
70 |   - set_type_to_cast
71 |   - short_array_syntax
72 |   - short_list_syntax
73 |   - simplified_if_return
74 |   - single_quote
75 |   - standardize_not_equals
76 |   - ternary_to_null_coalescing
77 |   - trailing_comma_in_multiline_array
78 |   - unalign_double_arrow
79 |   - unalign_equals
80 |   - empty_loop_body_braces
81 |   - integer_literal_case
82 |   - union_type_without_spaces
83 | 
84 | disabled:
85 |   - function_declaration
86 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "yiisoft/rate-limiter",
 3 |     "type": "library",
 4 |     "description": "Yii Rate Limiter Middleware",
 5 |     "keywords": [
 6 |         "yii",
 7 |         "rate limiter",
 8 |         "framework",
 9 |         "GCRA",
10 |         "middleware",
11 |         "PSR-15"
12 |     ],
13 |     "homepage": "https://www.yiiframework.com/",
14 |     "license": "BSD-3-Clause",
15 |     "support": {
16 |         "issues": "https://github.com/yiisoft/rate-limiter/issues?state=open",
17 |         "source": "https://github.com/yiisoft/rate-limiter",
18 |         "forum": "https://www.yiiframework.com/forum/",
19 |         "wiki": "https://www.yiiframework.com/wiki/",
20 |         "irc": "ircs://irc.libera.chat:6697/yii",
21 |         "chat": "https://t.me/yii3en"
22 |     },
23 |     "funding": [
24 |         {
25 |             "type": "opencollective",
26 |             "url": "https://opencollective.com/yiisoft"
27 |         },
28 |         {
29 |             "type": "github",
30 |             "url": "https://github.com/sponsors/yiisoft"
31 |         }
32 |     ],
33 |     "require": {
34 |         "php": "^8.0",
35 |         "psr/http-factory": "^1.0",
36 |         "psr/http-message": "^1.1|^2.0",
37 |         "psr/http-message-implementation": "1.0",
38 |         "psr/http-server-handler": "^1.0",
39 |         "psr/http-server-middleware": "^1.0",
40 |         "psr/simple-cache": "^2.0|^3.0",
41 |         "yiisoft/http": "^1.2"
42 |     },
43 |     "require-dev": {
44 |         "ext-apcu": "*",
45 |         "maglnet/composer-require-checker": "^4.4",
46 |         "nyholm/psr7": "^1.0",
47 |         "phpunit/phpunit": "^9.5",
48 |         "rector/rector": "^2.0.2",
49 |         "roave/infection-static-analysis-plugin": "^1.16",
50 |         "spatie/phpunit-watcher": "^1.23",
51 |         "vimeo/psalm": "^4.30|^5.13",
52 |         "yiisoft/cache": "^3.0"
53 |     },
54 |     "suggest": {
55 |         "ext-apcu": "To use APCu storage"
56 |     },
57 |     "autoload": {
58 |         "psr-4": {
59 |             "Yiisoft\\Yii\\RateLimiter\\": "src"
60 |         }
61 |     },
62 |     "autoload-dev": {
63 |         "psr-4": {
64 |             "Yiisoft\\Yii\\RateLimiter\\Tests\\": "tests"
65 |         }
66 |     },
67 |     "scripts": {
68 |         "test": "phpunit --testdox --no-interaction",
69 |         "test-watch": "phpunit-watcher watch"
70 |     },
71 |     "config": {
72 |         "sort-packages": true,
73 |         "allow-plugins": {
74 |             "infection/extension-installer": true,
75 |             "composer/package-versions-deprecated": true
76 |         }
77 |     }
78 | }
79 | 


--------------------------------------------------------------------------------
/src/LimitRequestsMiddleware.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Yii\RateLimiter;
 6 | 
 7 | use Psr\Http\Message\ResponseFactoryInterface;
 8 | use Psr\Http\Message\ResponseInterface;
 9 | use Psr\Http\Message\ServerRequestInterface;
10 | use Psr\Http\Server\MiddlewareInterface;
11 | use Psr\Http\Server\RequestHandlerInterface;
12 | use Yiisoft\Http\Status;
13 | use Yiisoft\Yii\RateLimiter\Policy\LimitPerIp;
14 | use Yiisoft\Yii\RateLimiter\Policy\LimitPolicyInterface;
15 | 
16 | /**
17 |  * RateLimiter helps to prevent abuse by limiting the number of requests that could be me made consequentially.
18 |  *
19 |  * For example, you may want to limit the API usage of each user to be at most 100 API calls within a period of 10
20 |  * minutes. If too many requests are received from a user within the stated period of the time, a response with status
21 |  * code 429 (meaning "Too Many Requests") should be returned.
22 |  *
23 |  * @psalm-type CounterIdCallback = callable(ServerRequestInterface):string
24 |  */
25 | final class LimitRequestsMiddleware implements MiddlewareInterface
26 | {
27 |     private LimitPolicyInterface $limitingPolicy;
28 | 
29 |     public function __construct(
30 |         private CounterInterface $counter,
31 |         private ResponseFactoryInterface $responseFactory,
32 |         LimitPolicyInterface|null $limitingPolicy = null,
33 |         private ?MiddlewareInterface $failStoreUpdatedDataMiddleware = null,
34 |     ) {
35 |         $this->limitingPolicy = $limitingPolicy ?: new LimitPerIp();
36 |     }
37 | 
38 |     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
39 |     {
40 |         $state = $this->counter->hit($this->limitingPolicy->fingerprint($request));
41 | 
42 |         if ($state->isLimitReached()) {
43 |             $response = $this->createErrorResponse();
44 |         } elseif ($state->isFailStoreUpdatedData() && $this->failStoreUpdatedDataMiddleware !== null) {
45 |             $response = $this->failStoreUpdatedDataMiddleware->process($request, $handler);
46 |         } else {
47 |             $response = $handler->handle($request);
48 |         }
49 | 
50 |         return $this->addHeaders($response, $state);
51 |     }
52 | 
53 |     private function createErrorResponse(): ResponseInterface
54 |     {
55 |         $response = $this->responseFactory->createResponse(Status::TOO_MANY_REQUESTS);
56 |         $response->getBody()->write(Status::TEXTS[Status::TOO_MANY_REQUESTS]);
57 | 
58 |         return $response;
59 |     }
60 | 
61 |     private function addHeaders(ResponseInterface $response, CounterState $result): ResponseInterface
62 |     {
63 |         return $response
64 |             ->withHeader('X-Rate-Limit-Limit', (string) $result->getLimit())
65 |             ->withHeader('X-Rate-Limit-Remaining', (string) $result->getRemaining())
66 |             ->withHeader('X-Rate-Limit-Reset', (string) $result->getResetTime());
67 |     }
68 | }
69 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | <p align="center">
  2 |     <a href="https://github.com/yiisoft" target="_blank">
  3 |         <img src="https://yiisoft.github.io/docs/images/yii_logo.svg" height="100px" alt="Yii">
  4 |     </a>
  5 |     <h1 align="center">Yii Rate Limiter Middleware</h1>
  6 |     <br>
  7 | </p>
  8 | 
  9 | [![Latest Stable Version](https://poser.pugx.org/yiisoft/rate-limiter/v/stable.png)](https://packagist.org/packages/yiisoft/rate-limiter)
 10 | [![Total Downloads](https://poser.pugx.org/yiisoft/rate-limiter/downloads.png)](https://packagist.org/packages/yiisoft/rate-limiter)
 11 | [![Build status](https://github.com/yiisoft/rate-limiter/workflows/build/badge.svg)](https://github.com/yiisoft/rate-limiter/actions?query=workflow%3Abuild)
 12 | [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/yiisoft/rate-limiter/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/yiisoft/rate-limiter/?branch=master)
 13 | [![Code Coverage](https://scrutinizer-ci.com/g/yiisoft/rate-limiter/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/yiisoft/rate-limiter/?branch=master)
 14 | [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fyiisoft%2Frate-limiter%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/rate-limiter/master)
 15 | [![static analysis](https://github.com/yiisoft/rate-limiter/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/rate-limiter/actions?query=workflow%3A%22static+analysis%22)
 16 | [![type-coverage](https://shepherd.dev/github/yiisoft/rate-limiter/coverage.svg)](https://shepherd.dev/github/yiisoft/rate-limiter)
 17 | 
 18 | Rate limiter middleware helps to prevent abuse by limiting the number of requests that could be me made consequentially.
 19 | 
 20 | For example, you may want to limit the API usage of each user to be at most 100 API calls within a period of 10 minutes.
 21 | If too many requests are received from a user within the stated period of the time, a response with status code 429
 22 | (meaning "Too Many Requests") should be returned.
 23 | 
 24 | ## Requirements
 25 | 
 26 | - PHP 8.0 or higher.
 27 | 
 28 | ## Installation
 29 | 
 30 | The package could be installed with [Composer](https://getcomposer.org):
 31 | 
 32 | ```shell
 33 | composer require yiisoft/rate-limiter
 34 | ```
 35 | 
 36 | ## General usage
 37 | 
 38 | ```php
 39 | use Psr\Http\Message\ServerRequestInterface;
 40 | use Yiisoft\Yii\RateLimiter\LimitRequestsMiddleware;
 41 | use Yiisoft\Yii\RateLimiter\Counter;
 42 | use Nyholm\Psr7\Factory\Psr17Factory;
 43 | use Yiisoft\Yii\RateLimiter\Policy\LimitAlways;
 44 | use Yiisoft\Yii\RateLimiter\Policy\LimitPerIp;
 45 | use Yiisoft\Yii\RateLimiter\Policy\LimitCallback;
 46 | use Yiisoft\Yii\RateLimiter\Storage\StorageInterface;
 47 | use Yiisoft\Yii\RateLimiter\Storage\SimpleCacheStorage;
 48 | 
 49 | /** @var StorageInterface $storage */
 50 | $storage = new SimpleCacheStorage($cache);
 51 | 
 52 | $counter = new Counter($storage, 2, 5);
 53 | $responseFactory = new Psr17Factory();
 54 | 
 55 | $middleware = new LimitRequestsMiddleware($counter, $responseFactory); // LimitPerIp by default
 56 | ```
 57 | 
 58 | In the above 2 is the maximum number of counter increments (requests) that could be performed before increments
 59 | are limited and 5 is a period to apply limit to, in seconds.
 60 | 
 61 | The `Counter` implements [generic cell rate limit algorithm (GCRA)](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm)
 62 | that ensures that after reaching the limit further increments are distributed equally.
 63 | 
 64 | > Note: While it is sufficiently effective, it is preferred to use [Nginx](https://www.nginx.com/blog/rate-limiting-nginx/)
 65 | > or another webserver capabilities for rate limiting. This package allows rate-limiting in the project with deployment
 66 | > environment you cannot control such as installable CMS. 
 67 | 
 68 | ### Implementing your own limiting policy
 69 | 
 70 | There are two ready to use limiting policies available in the package:
 71 | 
 72 | - `LimitAlways` - to count all incoming requests. 
 73 | - `LimitPerIp` - to count requests from different IPs separately.
 74 | 
 75 | These could be applied as follows:
 76 | 
 77 | ```php
 78 | $middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitPerIp());
 79 | // or
 80 | $middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitAlways());
 81 | ```
 82 | 
 83 | Easiest way to customize a policy is to use `LimitCallback`:
 84 | 
 85 | ```php
 86 | $middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitCallback(function (ServerRequestInterface $request): string {
 87 |     // return user id from database if authentication id used i.e. limit guests and each authenticated user separately.
 88 | }));
 89 | ```
 90 | 
 91 | Another way it to implement `Yiisoft\Yii\RateLimiter\Policy\LimitPolicyInterface` and use it in a similar way as above.
 92 | 
 93 | ### Implementing your own counter storage
 94 | 
 95 | There are two ready to use counter storages available in the package:
 96 | - `\Yiisoft\Yii\RateLimiter\Storage\SimpleCacheStorage` - stores counters in any [PSR-16](https://www.php-fig.org/psr/psr-16/) cache.
 97 | - `\Yiisoft\Yii\RateLimiter\Storage\ApcuStorage` - stores counters by using the [APCu PHP extension](https://www.php.net/apcu) while taking concurrency into account.
 98 | 
 99 | To use your own storage implement `Yiisoft\Yii\RateLimiter\Storage\StorageInterface`. 
100 | 
101 | ## Documentation
102 | 
103 | - [Internals](docs/internals.md)
104 | 
105 | If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
106 | You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
107 | 
108 | ## License
109 | 
110 | The Yii Rate Limiter Middleware is free software. It is released under the terms of the BSD License.
111 | Please see [`LICENSE`](./LICENSE.md) for more information.
112 | 
113 | Maintained by [Yii Software](https://www.yiiframework.com/).
114 | 
115 | ## Support the project
116 | 
117 | [![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective&logoColor=7eadf1&labelColor=555555)](https://opencollective.com/yiisoft)
118 | 
119 | ## Follow updates
120 | 
121 | [![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/)
122 | [![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter&logoColor=1DA1F2&labelColor=555555?style=flat)](https://twitter.com/yiiframework)
123 | [![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en)
124 | [![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)
125 | [![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack)
126 | 


--------------------------------------------------------------------------------
/src/Counter.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Yii\RateLimiter;
  6 | 
  7 | use InvalidArgumentException;
  8 | use Yiisoft\Yii\RateLimiter\Storage\StorageInterface;
  9 | use Yiisoft\Yii\RateLimiter\Time\MicrotimeTimer;
 10 | use Yiisoft\Yii\RateLimiter\Time\TimerInterface;
 11 | 
 12 | /**
 13 |  * Counter implements generic cell rate limit algorithm (GCRA) that ensures that after reaching the limit further
 14 |  * increments are distributed equally.
 15 |  *
 16 |  * @link https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm
 17 |  */
 18 | final class Counter implements CounterInterface
 19 | {
 20 |     private const DEFAULT_TTL = 86400;
 21 |     private const ID_PREFIX = 'rate-limiter-';
 22 |     private const MILLISECONDS_PER_SECOND = 1000;
 23 |     private const DEFAULT_MAX_CAS_ATTEMPTS = 10;
 24 | 
 25 |     /**
 26 |      * @var int Period to apply limit to.
 27 |      */
 28 |     private int $periodInMilliseconds;
 29 | 
 30 |     /**
 31 |      * @var float Maximum interval before next increment.
 32 |      * In GCRA it is known as emission interval.
 33 |      */
 34 |     private float $incrementIntervalInMilliseconds;
 35 |     private TimerInterface $timer;
 36 | 
 37 |     /**
 38 |      * @param StorageInterface $storage Storage to use for counter values.
 39 |      * @param int $limit Maximum number of increments that could be performed before increments are limited.
 40 |      * @param int $periodInSeconds Period to apply limit to.
 41 |      * @param int $storageTtlInSeconds Storage TTL. Should be higher than `$periodInSeconds`.
 42 |      * @param string $storagePrefix Storage prefix.
 43 |      * @param TimerInterface|null $timer Timer instance to get current time from.
 44 |      * @param int $maxCasAttempts Maximum number of times to retry saveIfNotExists/saveCompareAndSwap operations before returning an error.
 45 |      */
 46 |     public function __construct(
 47 |         private StorageInterface $storage,
 48 |         private int $limit,
 49 |         int $periodInSeconds,
 50 |         private int $storageTtlInSeconds = self::DEFAULT_TTL,
 51 |         private string $storagePrefix = self::ID_PREFIX,
 52 |         TimerInterface|null $timer = null,
 53 |         private int $maxCasAttempts = self::DEFAULT_MAX_CAS_ATTEMPTS,
 54 |     ) {
 55 |         if ($limit < 1) {
 56 |             throw new InvalidArgumentException('The limit must be a positive value.');
 57 |         }
 58 | 
 59 |         if ($periodInSeconds < 1) {
 60 |             throw new InvalidArgumentException('The period must be a positive value.');
 61 |         }
 62 | 
 63 |         $this->periodInMilliseconds = $periodInSeconds * self::MILLISECONDS_PER_SECOND;
 64 |         $this->timer = $timer ?: new MicrotimeTimer();
 65 |         $this->incrementIntervalInMilliseconds = $this->periodInMilliseconds / $this->limit;
 66 |     }
 67 | 
 68 |     /**
 69 |      * {@inheritdoc}
 70 |      */
 71 |     public function hit(string $id): CounterState
 72 |     {
 73 |         $attempts = 0;
 74 |         $isFailStoreUpdatedData = false;
 75 |         do {
 76 |             // Last increment time.
 77 |             // In GCRA it's known as arrival time.
 78 |             $lastIncrementTimeInMilliseconds = $this->timer->nowInMilliseconds();
 79 | 
 80 |             $lastStoredTheoreticalNextIncrementTime = $this->getLastStoredTheoreticalNextIncrementTime($id);
 81 | 
 82 |             $theoreticalNextIncrementTime = $this->calculateTheoreticalNextIncrementTime(
 83 |                 $lastIncrementTimeInMilliseconds,
 84 |                 $lastStoredTheoreticalNextIncrementTime
 85 |             );
 86 | 
 87 |             $remaining = $this->calculateRemaining($lastIncrementTimeInMilliseconds, $theoreticalNextIncrementTime);
 88 |             $resetAfter = $this->calculateResetAfter($theoreticalNextIncrementTime);
 89 | 
 90 |             if ($remaining === 0) {
 91 |                 break;
 92 |             }
 93 | 
 94 |             $isStored = $this->storeTheoreticalNextIncrementTime(
 95 |                 $id,
 96 |                 $theoreticalNextIncrementTime,
 97 |                 $lastStoredTheoreticalNextIncrementTime
 98 |             );
 99 |             if ($isStored) {
100 |                 break;
101 |             }
102 | 
103 |             $attempts++;
104 |             if ($attempts >= $this->maxCasAttempts) {
105 |                 $isFailStoreUpdatedData = true;
106 |                 break;
107 |             }
108 |         } while (true);
109 | 
110 |         return new CounterState($this->limit, $remaining, $resetAfter, $isFailStoreUpdatedData);
111 |     }
112 | 
113 |     /**
114 |      * @return float Theoretical increment time that would be expected from equally spaced increments at exactly rate
115 |      * limit. In GCRA it is known as TAT, theoretical arrival time.
116 |      */
117 |     private function calculateTheoreticalNextIncrementTime(
118 |         float $lastIncrementTimeInMilliseconds,
119 |         ?float $storedTheoreticalNextIncrementTime
120 |     ): float {
121 |         return (
122 |             $storedTheoreticalNextIncrementTime === null
123 |                 ? $lastIncrementTimeInMilliseconds
124 |                 : max($lastIncrementTimeInMilliseconds, $storedTheoreticalNextIncrementTime)
125 |         ) + $this->incrementIntervalInMilliseconds;
126 |     }
127 | 
128 |     /**
129 |      * @return int The number of remaining requests in the current time period.
130 |      */
131 |     private function calculateRemaining(
132 |         float $lastIncrementTimeInMilliseconds,
133 |         float $theoreticalNextIncrementTime
134 |     ): int {
135 |         $incrementAllowedAt = $theoreticalNextIncrementTime - $this->periodInMilliseconds;
136 | 
137 |         $remainingTimeInMilliseconds = round($lastIncrementTimeInMilliseconds - $incrementAllowedAt);
138 |         if ($remainingTimeInMilliseconds > 0) {
139 |             return (int) ($remainingTimeInMilliseconds / $this->incrementIntervalInMilliseconds);
140 |         }
141 | 
142 |         return 0;
143 |     }
144 | 
145 |     private function getLastStoredTheoreticalNextIncrementTime(string $id): ?float
146 |     {
147 |         return $this->storage->get($this->getStorageKey($id));
148 |     }
149 | 
150 |     private function storeTheoreticalNextIncrementTime(
151 |         string $id,
152 |         float $theoreticalNextIncrementTime,
153 |         ?float $lastStoredTheoreticalNextIncrementTime
154 |     ): bool {
155 |         if ($lastStoredTheoreticalNextIncrementTime !== null) {
156 |             return $this->storage->saveCompareAndSwap(
157 |                 $this->getStorageKey($id),
158 |                 $lastStoredTheoreticalNextIncrementTime,
159 |                 $theoreticalNextIncrementTime,
160 |                 $this->storageTtlInSeconds
161 |             );
162 |         }
163 | 
164 |         return $this->storage->saveIfNotExists(
165 |             $this->getStorageKey($id),
166 |             $theoreticalNextIncrementTime,
167 |             $this->storageTtlInSeconds
168 |         );
169 |     }
170 | 
171 |     /**
172 |      * @return int Timestamp to wait until the rate limit resets.
173 |      */
174 |     private function calculateResetAfter(float $theoreticalNextIncrementTime): int
175 |     {
176 |         return (int) ($theoreticalNextIncrementTime / self::MILLISECONDS_PER_SECOND);
177 |     }
178 | 
179 |     /**
180 |      * @return string Storage key used to store the next increment time.
181 |      */
182 |     private function getStorageKey(string $id): string
183 |     {
184 |         return $this->storagePrefix . $id;
185 |     }
186 | }
187 | 


--------------------------------------------------------------------------------