feat(cache): update device-detector cache configuration options

Author: BrianHigby

README.md

@@ -170,7 +170,7 @@ Available options:
 | :--------------------------- | :-------: | :----------------------------------------------------- |
 | `cache.interval`             |  `10080`  | Cache TTL in seconds                                   |
 | `cache.prefix`               |  `bd4_`   | Cache key prefix                                       |
-| `cache.device-detector`      |  `false`  | Enable matomo/device-detector's internal Laravel cache |
+| `cache.device-detector`      |  `null`   | Cache driver for device-detector's internal cache. See `config/browser-detect.php` for examples. |
 | `security.max-header-length` |  `2048`   | Max user agent length (DoS protection)                 |
 
 ## Quality

config/browser-detect.php

@@ -11,12 +11,14 @@
          */
         'prefix' => 'bd4_',
         /**
-         * Enable the device-detector engine's own internal cache via Laravel's cache store.
-         * When enabled, parsed YAML device definition data is cached by the underlying
-         * matomo/device-detector library, reducing file reads on repeated parses.
-         * Requires a Laravel application context — do not enable in standalone mode.
+         * Cache driver class for the device-detector engine's internal cache. When null,
+         * the library uses its built-in StaticCache. Override to swap in a different driver.
+         *
+         * Examples:
+         *   \DeviceDetector\Cache\StaticCache::class   — in-process static cache (default)
+         *   \DeviceDetector\Cache\LaravelCache::class  — persists via Laravel's cache store
          */
-        'device-detector' => false,
+        'device-detector' => null,
     ],
     'security' => [
         /**

src/Parser.php

@@ -2,6 +2,7 @@
 
 namespace hisorange\BrowserDetect;
 
+use DeviceDetector\Cache\CacheInterface;
 use hisorange\BrowserDetect\Contracts\ParserInterface;
 use hisorange\BrowserDetect\Contracts\ResultInterface;
 use hisorange\BrowserDetect\Contracts\StageInterface;
@@ -202,11 +203,11 @@ protected function makeHashKey(string $agent): string
     }
 
     /**
-     * @return array{interval: int, prefix: string, device-detector: bool}
+     * @return array{interval: int, prefix: string, device-detector: class-string<CacheInterface>|null}
      */
     private function cacheConfig(): array
     {
-        /** @var array{interval: int, prefix: string, device-detector: bool} */
+        /** @var array{interval: int, prefix: string, device-detector: class-string<CacheInterface>|null} */
         return $this->config['cache'];
     }
 

src/Stages/DeviceDetector.php

@@ -2,6 +2,7 @@
 
 namespace hisorange\BrowserDetect\Stages;
 
+use DeviceDetector\Cache\CacheInterface;
 use DeviceDetector\Parser\Device\AbstractDeviceParser;
 use hisorange\BrowserDetect\Contracts\PayloadInterface;
 use hisorange\BrowserDetect\Contracts\StageInterface;
@@ -13,16 +14,20 @@ class DeviceDetector implements StageInterface
 {
     protected ?\DeviceDetector\DeviceDetector $detector = null;
 
-    public function __construct(protected bool $useDeviceDetectorCache = false) {}
+    /**
+     * @param  class-string<CacheInterface>|null  $deviceDetectorCache
+     */
+    public function __construct(protected ?string $deviceDetectorCache = null) {}
 
     public function __invoke(PayloadInterface $payload): PayloadInterface
     {
         if ($this->detector === null) {
             $this->detector = new \DeviceDetector\DeviceDetector;
             // Skip bot detection — CrawlerDetect handles that upstream.
             $this->detector->skipBotDetection(true);
-            if ($this->useDeviceDetectorCache) {
-                $this->detector->setCache(new \DeviceDetector\Cache\LaravelCache());
+            if ($this->deviceDetectorCache !== null) {
+                $cacheClass = $this->deviceDetectorCache;
+                $this->detector->setCache(new $cacheClass);
             }
         }
         $this->detector->setUserAgent($payload->getAgent());

tests/Stages/DeviceDetectorTest.php

@@ -2,6 +2,7 @@
 
 namespace hisorange\BrowserDetect\Test\Stages;
 
+use DeviceDetector\Cache\LaravelCache;
 use hisorange\BrowserDetect\Payload;
 use hisorange\BrowserDetect\Stages\DeviceDetector;
 use hisorange\BrowserDetect\Test\TestCase;
@@ -87,7 +88,7 @@ public function test_invoke_with_device_detector_cache_enabled()
         // Must be called before the stage runs to intercept cache writes.
         Cache::spy();
 
-        $stage = new DeviceDetector(useDeviceDetectorCache: true);
+        $stage = new DeviceDetector(deviceDetectorCache: LaravelCache::class);
         $payload = new Payload('Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.108 Safari/537.36');
         $stage($payload);