maatify/rate-limiter

Flexible PSR-15 rate limiter supporting Redis, MongoDB, and MySQL via real and fake drivers. Provides multi-strategy algorithms, burst control, sliding window, token bucket, and integration with Maatify Data Repository.

dev-main 2025-12-08 07:11 UTC

Requires

• php: >=8.4
• maatify/psr-logger: ^1.0
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• doctrine/dbal: ^4.3
• friendsofphp/php-cs-fixer: ^3.60
• maatify/data-fakes: ^1.0
• mongodb/mongodb: ^2.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0
• predis/predis: ^2.3

Suggests

• ext-mongodb: Required for MongoAdapter.
• ext-pdo: Required for MySQLAdapter (PDO driver).
• ext-redis: High-performance RedisAdapter.
• doctrine/dbal: Optional advanced SQL driver for MySQLDbalAdapter.
• maatify/data-adapters: Real adapter support for Redis, MongoDB, MySQL drivers.
• maatify/data-fakes: Test the rate limiter using deterministic in-memory fake drivers.
• maatify/data-repository: Use repository abstraction across Redis, MySQL, Mongo with FakeAdapters support.
• mongodb/mongodb: Needed if using MongoAdapter.
• predis/predis: Redis fallback when ext-redis is unavailable.

MIT

• Mohamed Abdulalim
• Maatify.dev

• redis
• mysql
• mongo
• throttle
• pdo
• middleware
• limit
• psr-7
• rate-limit
• psr-15
• token-bucket
• leaky-bucket
• rate-limiter
• maatify
• sliding-window
• traffic-control

README

PSR-compliant distributed rate limiting engine supporting Redis, MongoDB, and MySQL with adaptive exponential backoff.

🚀 Overview

Maatify Rate Limiter is a fully decoupled, PSR-compliant rate-limiting engine designed for:

• Native PHP
• Slim Framework
• Laravel Middleware
• Custom API Gateways

It provides distributed rate-limiting with adaptive exponential backoff, unified across:

• Redis
• MongoDB
• MySQL

Why this library?

• Zero storage lock-in
• Unified attempt/status/reset API
• Global per-IP rate limit
• Adaptive Exponential Backoff (2ⁿ)
• Full PSR-7 / PSR-15 middleware compatibility
• PHPStan Level Max ready

✅ Supported Drivers

Backend	Driver Type	Use Case
Redis	Real Driver	High-performance in-memory limits
MongoDB	Real Driver	Distributed analytics
MySQL	Real Driver	Persistent audit & compliance

📦 Installation

composer require maatify/rate-limiter

⚡ Quick Usage

use Maatify\RateLimiter\Resolver\RateLimiterResolver;
use Maatify\RateLimiter\Enums\RateLimitActionEnum;
use Maatify\RateLimiter\Enums\PlatformEnum;

$resolver = new RateLimiterResolver(['driver' => 'redis']);
$limiter  = $resolver->resolve();

$status = $limiter->attempt(
    '127.0.0.1',
    RateLimitActionEnum::LOGIN,
    PlatformEnum::WEB
);

echo $status->remaining;

📘 Full usage examples (Native, Slim, Laravel, API, Enums, Backoff): ➡️ examples/Examples.md

🧩 Key Features

• Unified API: attempt(), status(), reset()
• Global Per-IP Limit
• Adaptive Exponential Backoff
• DTO-based Response Model
• PSR-7 / PSR-15 Middleware Ready
• Custom Enum Contracts
• Driver Resolver
• Strict Validation & Type Safety
• PHPStan Level Max

📄 Documentation

• Arabic Documentation
• Usage Examples
• Changelog
• Security Policy

📚 Development History & Phase Details

• Phase 1 – Environment Setup
• Phase 2 – Core Architecture
• Phase 3 – Storage Drivers
• Phase 3.1 – Enum Contracts Refactor
• Phase 4 – Resolver & Middleware
• Phase 4.1 – Continuous Integration
• Phase 5 – Exponential Backoff & Global Rate Limit

🧱 Dependencies Overview

maatify/rate-limiter relies on PSR standards and selected open-source libraries.

🔌 Direct Open-Source Dependencies

Library	Purpose
psr/http-message	HTTP message interfaces
psr/http-server-middleware	PSR-15 middleware
psr/http-server-handler	Request handler
redis / predis	Redis driver
mongodb/mongodb	MongoDB driver
phpunit/phpunit	Testing
phpstan/phpstan	Static analysis

🧪 Testing

composer test

Runs:

• Driver consistency tests
• Resolver tests
• Middleware header tests
• Backoff & global limit tests
• Coverage reporting

🪪 License

MIT License © Maatify.dev — Free to use, modify, and distribute with attribution.

👤 Author

Engineered by Mohamed Abdulalim (@megyptm)
Backend Lead & Technical Architect — https://www.maatify.dev

🤝 Contributors

Special thanks to the Maatify.dev engineering team and all open-source contributors. Your efforts help make this library stable, secure, and production-ready.

Before opening a Pull Request, please read:

• Contributing Guide
• Code of Conduct

_{Built with ❤️ by Maatify.dev — Unified Ecosystem for Modern PHP Libraries}