{"id":14966346,"url":"https://github.com/yiisoft/rate-limiter","last_synced_at":"2025-08-05T16:05:46.864Z","repository":{"id":39586466,"uuid":"254919191","full_name":"yiisoft/rate-limiter","owner":"yiisoft","description":"RateLimiter helps to prevent abuse by limiting the number of requests that could be me made consequentially.","archived":false,"fork":false,"pushed_at":"2024-04-04T15:07:27.000Z","size":112,"stargazers_count":28,"open_issues_count":0,"forks_count":10,"subscribers_count":20,"default_branch":"master","last_synced_at":"2024-04-15T03:05:23.626Z","etag":null,"topics":["gcra","hacktoberfest","middleware","psr-15","rate-limiter","yii3"],"latest_commit_sha":null,"homepage":"https://www.yiiframework.com/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yiisoft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"open_collective":"yiisoft","github":["yiisoft"]}},"created_at":"2020-04-11T17:26:24.000Z","updated_at":"2024-04-17T04:44:04.741Z","dependencies_parsed_at":"2024-01-11T14:14:23.480Z","dependency_job_id":"bd9db563-c602-4063-8d2f-2a630bf038ee","html_url":"https://github.com/yiisoft/rate-limiter","commit_stats":{"total_commits":73,"total_committers":16,"mean_commits":4.5625,"dds":0.6027397260273972,"last_synced_commit":"61002ff881cfb3f285039d7f347519c73fbf939c"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":"yiisoft/package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Frate-limiter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Frate-limiter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Frate-limiter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Frate-limiter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yiisoft","download_url":"https://codeload.github.com/yiisoft/rate-limiter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219865487,"owners_count":16554152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gcra","hacktoberfest","middleware","psr-15","rate-limiter","yii3"],"created_at":"2024-09-24T13:36:15.104Z","updated_at":"2024-09-24T14:05:12.871Z","avatar_url":"https://github.com/yiisoft.png","language":"PHP","funding_links":["https://opencollective.com/yiisoft","https://github.com/sponsors/yiisoft"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/yiisoft\" target=\"_blank\"\u003e\n        \u003cimg src=\"https://yiisoft.github.io/docs/images/yii_logo.svg\" height=\"100px\" alt=\"Yii\"\u003e\n    \u003c/a\u003e\n    \u003ch1 align=\"center\"\u003eYii Rate Limiter Middleware\u003c/h1\u003e\n    \u003cbr\u003e\n\u003c/p\u003e\n\n[![Latest Stable Version](https://poser.pugx.org/yiisoft/rate-limiter/v/stable.png)](https://packagist.org/packages/yiisoft/rate-limiter)\n[![Total Downloads](https://poser.pugx.org/yiisoft/rate-limiter/downloads.png)](https://packagist.org/packages/yiisoft/rate-limiter)\n[![Build status](https://github.com/yiisoft/rate-limiter/workflows/build/badge.svg)](https://github.com/yiisoft/rate-limiter/actions?query=workflow%3Abuild)\n[![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)\n[![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)\n[![Mutation testing badge](https://img.shields.io/endpoint?style=flat\u0026url=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)\n[![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)\n[![type-coverage](https://shepherd.dev/github/yiisoft/rate-limiter/coverage.svg)](https://shepherd.dev/github/yiisoft/rate-limiter)\n\nRate limiter middleware helps to prevent abuse by limiting the number of requests that could be me made consequentially.\n\nFor 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.\nIf too many requests are received from a user within the stated period of the time, a response with status code 429\n(meaning \"Too Many Requests\") should be returned.\n\n## Requirements\n\n- PHP 8.0 or higher.\n\n## Installation\n\nThe package could be installed with [Composer](https://getcomposer.org):\n\n```shell\ncomposer require yiisoft/rate-limiter\n```\n\n## General usage\n\n```php\nuse Psr\\Http\\Message\\ServerRequestInterface;\nuse Yiisoft\\Yii\\RateLimiter\\LimitRequestsMiddleware;\nuse Yiisoft\\Yii\\RateLimiter\\Counter;\nuse Nyholm\\Psr7\\Factory\\Psr17Factory;\nuse Yiisoft\\Yii\\RateLimiter\\Policy\\LimitAlways;\nuse Yiisoft\\Yii\\RateLimiter\\Policy\\LimitPerIp;\nuse Yiisoft\\Yii\\RateLimiter\\Policy\\LimitCallback;\nuse Yiisoft\\Yii\\RateLimiter\\Storage\\StorageInterface;\nuse Yiisoft\\Yii\\RateLimiter\\Storage\\SimpleCacheStorage;\n\n/** @var StorageInterface $storage */\n$storage = new SimpleCacheStorage($cache);\n\n$counter = new Counter($storage, 2, 5);\n$responseFactory = new Psr17Factory();\n\n$middleware = new LimitRequestsMiddleware($counter, $responseFactory); // LimitPerIp by default\n```\n\nIn the above 2 is the maximum number of counter increments (requests) that could be performed before increments\nare limited and 5 is a period to apply limit to, in seconds.\n\nThe `Counter` implements [generic cell rate limit algorithm (GCRA)](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm)\nthat ensures that after reaching the limit further increments are distributed equally.\n\n\u003e Note: While it is sufficiently effective, it is preferred to use [Nginx](https://www.nginx.com/blog/rate-limiting-nginx/)\n\u003e or another webserver capabilities for rate limiting. This package allows rate-limiting in the project with deployment\n\u003e environment you cannot control such as installable CMS. \n\n### Implementing your own limiting policy\n\nThere are two ready to use limiting policies available in the package:\n\n- `LimitAlways` - to count all incoming requests. \n- `LimitPerIp` - to count requests from different IPs separately.\n\nThese could be applied as follows:\n\n```php\n$middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitPerIp());\n// or\n$middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitAlways());\n```\n\nEasiest way to customize a policy is to use `LimitCallback`:\n\n```php\n$middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitCallback(function (ServerRequestInterface $request): string {\n    // return user id from database if authentication id used i.e. limit guests and each authenticated user separately.\n}));\n```\n\nAnother way it to implement `Yiisoft\\Yii\\RateLimiter\\Policy\\LimitPolicyInterface` and use it in a similar way as above.\n\n### Implementing your own counter storage\n\nThere are two ready to use counter storages available in the package:\n- `\\Yiisoft\\Yii\\RateLimiter\\Storage\\SimpleCacheStorage` - stores counters in any [PSR-16](https://www.php-fig.org/psr/psr-16/) cache.\n- `\\Yiisoft\\Yii\\RateLimiter\\Storage\\ApcuStorage` - stores counters by using the [APCu PHP extension](https://www.php.net/apcu) while taking concurrency into account.\n\nTo use your own storage implement `Yiisoft\\Yii\\RateLimiter\\Storage\\StorageInterface`. \n\n## Documentation\n\n- [Internals](docs/internals.md)\n\nIf 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.\nYou may also check out other [Yii Community Resources](https://www.yiiframework.com/community).\n\n## License\n\nThe Yii Rate Limiter Middleware is free software. It is released under the terms of the BSD License.\nPlease see [`LICENSE`](./LICENSE.md) for more information.\n\nMaintained by [Yii Software](https://www.yiiframework.com/).\n\n## Support the project\n\n[![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective\u0026logoColor=7eadf1\u0026labelColor=555555)](https://opencollective.com/yiisoft)\n\n## Follow updates\n\n[![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/)\n[![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter\u0026logoColor=1DA1F2\u0026labelColor=555555?style=flat)](https://twitter.com/yiiframework)\n[![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat\u0026logo=telegram)](https://t.me/yii3en)\n[![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat\u0026logo=facebook\u0026logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)\n[![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat\u0026logo=slack)](https://yiiframework.com/go/slack)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyiisoft%2Frate-limiter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyiisoft%2Frate-limiter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyiisoft%2Frate-limiter/lists"}