feat(cache): add BackedEnum and UnitEnum support to RateLimiter

- Add enum support to for() and limiter() methods for named rate limiters
- Add resolveLimiterName() helper using enum_value()
- Add comprehensive enum tests covering BackedEnum, UnitEnum, and
  string interoperability

Following Laravel's approach where only named limiter methods support
enums (for/limiter), not key-based methods (attempt/hit/etc) since
those typically use dynamic concatenated keys.

Author: binaryfire

src/cache/src/RateLimiter.php

@@ -4,9 +4,13 @@
 
 namespace Hypervel\Cache;
 
+use BackedEnum;
 use Closure;
 use Hyperf\Support\Traits\InteractsWithTime;
 use Hypervel\Cache\Contracts\Factory as Cache;
+use UnitEnum;
+
+use function Hypervel\Support\enum_value;
 
 class RateLimiter
 {
@@ -33,19 +37,27 @@ public function __construct(Cache $cache)
     /**
      * Register a named limiter configuration.
      */
-    public function for(string $name, Closure $callback): static
+    public function for(BackedEnum|UnitEnum|string $name, Closure $callback): static
     {
-        $this->limiters[$name] = $callback;
+        $this->limiters[$this->resolveLimiterName($name)] = $callback;
 
         return $this;
     }
 
     /**
      * Get the given named rate limiter.
      */
-    public function limiter(string $name): ?Closure
+    public function limiter(BackedEnum|UnitEnum|string $name): ?Closure
+    {
+        return $this->limiters[$this->resolveLimiterName($name)] ?? null;
+    }
+
+    /**
+     * Resolve the rate limiter name.
+     */
+    private function resolveLimiterName(BackedEnum|UnitEnum|string $name): string
     {
-        return $this->limiters[$name] ?? null;
+        return (string) enum_value($name);
     }
 
     /**

tests/Cache/RateLimiterEnumTest.php

@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Cache;
+
+use Hypervel\Cache\Contracts\Factory as Cache;
+use Hypervel\Cache\RateLimiter;
+use Hypervel\Tests\TestCase;
+use Mockery as m;
+use PHPUnit\Framework\Attributes\DataProvider;
+use ReflectionProperty;
+
+enum BackedEnumNamedRateLimiter: string
+{
+    case API = 'api';
+    case Web = 'web';
+}
+
+enum UnitEnumNamedRateLimiter
+{
+    case ThirdParty;
+    case Internal;
+}
+
+/**
+ * @internal
+ * @coversNothing
+ */
+class RateLimiterEnumTest extends TestCase
+{
+    #[DataProvider('registerNamedRateLimiterDataProvider')]
+    public function testRegisterNamedRateLimiter(mixed $name, string $expected): void
+    {
+        $reflectedLimitersProperty = new ReflectionProperty(RateLimiter::class, 'limiters');
+
+        $rateLimiter = new RateLimiter(m::mock(Cache::class));
+        $rateLimiter->for($name, fn () => 'limit');
+
+        $limiters = $reflectedLimitersProperty->getValue($rateLimiter);
+
+        $this->assertArrayHasKey($expected, $limiters);
+
+        $limiterClosure = $rateLimiter->limiter($name);
+
+        $this->assertNotNull($limiterClosure);
+    }
+
+    public static function registerNamedRateLimiterDataProvider(): array
+    {
+        return [
+            'uses BackedEnum' => [BackedEnumNamedRateLimiter::API, 'api'],
+            'uses UnitEnum' => [UnitEnumNamedRateLimiter::ThirdParty, 'ThirdParty'],
+            'uses normal string' => ['yolo', 'yolo'],
+        ];
+    }
+
+    public function testForWithBackedEnumStoresUnderValue(): void
+    {
+        $rateLimiter = new RateLimiter(m::mock(Cache::class));
+        $rateLimiter->for(BackedEnumNamedRateLimiter::API, fn () => 'api-limit');
+
+        // Can retrieve with enum
+        $this->assertNotNull($rateLimiter->limiter(BackedEnumNamedRateLimiter::API));
+
+        // Can also retrieve with string value
+        $this->assertNotNull($rateLimiter->limiter('api'));
+
+        // Closure returns expected value
+        $this->assertSame('api-limit', $rateLimiter->limiter(BackedEnumNamedRateLimiter::API)());
+    }
+
+    public function testForWithUnitEnumStoresUnderName(): void
+    {
+        $rateLimiter = new RateLimiter(m::mock(Cache::class));
+        $rateLimiter->for(UnitEnumNamedRateLimiter::ThirdParty, fn () => 'third-party-limit');
+
+        // Can retrieve with enum
+        $this->assertNotNull($rateLimiter->limiter(UnitEnumNamedRateLimiter::ThirdParty));
+
+        // Can also retrieve with string name (PascalCase)
+        $this->assertNotNull($rateLimiter->limiter('ThirdParty'));
+
+        // Closure returns expected value
+        $this->assertSame('third-party-limit', $rateLimiter->limiter(UnitEnumNamedRateLimiter::ThirdParty)());
+    }
+
+    public function testLimiterReturnsNullForNonExistentEnum(): void
+    {
+        $rateLimiter = new RateLimiter(m::mock(Cache::class));
+
+        $this->assertNull($rateLimiter->limiter(BackedEnumNamedRateLimiter::Web));
+        $this->assertNull($rateLimiter->limiter(UnitEnumNamedRateLimiter::Internal));
+    }
+
+    public function testBackedEnumAndStringInteroperability(): void
+    {
+        $rateLimiter = new RateLimiter(m::mock(Cache::class));
+
+        // Register with string
+        $rateLimiter->for('api', fn () => 'string-registered');
+
+        // Retrieve with BackedEnum that has same value
+        $limiter = $rateLimiter->limiter(BackedEnumNamedRateLimiter::API);
+
+        $this->assertNotNull($limiter);
+        $this->assertSame('string-registered', $limiter());
+    }
+
+    public function testUnitEnumAndStringInteroperability(): void
+    {
+        $rateLimiter = new RateLimiter(m::mock(Cache::class));
+
+        // Register with string (matching UnitEnum name)
+        $rateLimiter->for('ThirdParty', fn () => 'string-registered');
+
+        // Retrieve with UnitEnum
+        $limiter = $rateLimiter->limiter(UnitEnumNamedRateLimiter::ThirdParty);
+
+        $this->assertNotNull($limiter);
+        $this->assertSame('string-registered', $limiter());
+    }
+
+    public function testMultipleEnumLimitersCanCoexist(): void
+    {
+        $rateLimiter = new RateLimiter(m::mock(Cache::class));
+
+        $rateLimiter->for(BackedEnumNamedRateLimiter::API, fn () => 'api-limit');
+        $rateLimiter->for(BackedEnumNamedRateLimiter::Web, fn () => 'web-limit');
+        $rateLimiter->for(UnitEnumNamedRateLimiter::ThirdParty, fn () => 'third-party-limit');
+        $rateLimiter->for('custom', fn () => 'custom-limit');
+
+        $this->assertSame('api-limit', $rateLimiter->limiter(BackedEnumNamedRateLimiter::API)());
+        $this->assertSame('web-limit', $rateLimiter->limiter(BackedEnumNamedRateLimiter::Web)());
+        $this->assertSame('third-party-limit', $rateLimiter->limiter(UnitEnumNamedRateLimiter::ThirdParty)());
+        $this->assertSame('custom-limit', $rateLimiter->limiter('custom')());
+    }
+}