From 671ec8eb4c95e3b7ba96f02627c13c76403de93c Mon Sep 17 00:00:00 2001
From: Arif Hoque <arif@sulaco-tec.com>
Date: Thu, 5 Mar 2026 15:28:18 +0600
Subject: [PATCH] feat: Add #[Throttle] Attribute for Rate Limiting

---
 src/Phaseolies/Support/Router.php             | 23 +++++++++++++++++++
 .../Utilities/Attributes/Throttle.php         | 20 ++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 src/Phaseolies/Utilities/Attributes/Throttle.php

diff --git a/src/Phaseolies/Support/Router.php b/src/Phaseolies/Support/Router.php
index 860fff2..13b9c2c 100644
--- a/src/Phaseolies/Support/Router.php
+++ b/src/Phaseolies/Support/Router.php
@@ -1053,6 +1053,28 @@ protected function loadRoutesFromFiles(): void
         }
     }
 
+    /**
+     * Process Throttle attribute from controller method
+     *
+     * @param \ReflectionMethod $method
+     * @return void
+     */
+    protected function processThrottleAttribute(\ReflectionMethod $method): void
+    {
+        $throttleAttributes = $method->getAttributes(\Phaseolies\Utilities\Attributes\Throttle::class);
+
+        if (empty($throttleAttributes)) {
+            return;
+        }
+
+        $throttle = $throttleAttributes[0]->newInstance();
+
+        // Convert to middleware format: throttle:60,1
+        $middlewareKey = "throttle:{$throttle->maxAttempts},{$throttle->decayMinutes}";
+
+        $this->middleware($middlewareKey);
+    }
+
     /**
      * Handle attributes based middleware defination
      *
@@ -1080,6 +1102,7 @@ protected function processControllerMiddleware(array|string $callback): void
             $methodMiddlewareAttributes = $method->getAttributes(Middleware::class);
             $this->processAttributesMiddlewares($methodMiddlewareAttributes);
             $this->processRateLimitAnnotation($method);
+            $this->processThrottleAttribute($method);
         }
     }
 
diff --git a/src/Phaseolies/Utilities/Attributes/Throttle.php b/src/Phaseolies/Utilities/Attributes/Throttle.php
new file mode 100644
index 0000000..dc06e41
--- /dev/null
+++ b/src/Phaseolies/Utilities/Attributes/Throttle.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace Phaseolies\Utilities\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+final class Throttle
+{
+    /**
+     * Rate limit configuration
+     *
+     * @param int $maxAttempts Maximum requests allowed
+     * @param int $decayMinutes Time window in minutes
+     */
+    public function __construct(
+        public int $maxAttempts = 60,
+        public int $decayMinutes = 1
+    ) {}
+}