feat(cache): add device-detector cache option to improve performance

Author: BrianHigby

README.md

@@ -166,11 +166,12 @@ $browser = new Parser(null, null, [
 
 Available options:
 
-| Key                          | Default | Description                            |
-| :--------------------------- | :-----: | :------------------------------------- |
-| `cache.interval`             | `10080` | Cache TTL in seconds                   |
-| `cache.prefix`               | `bd4_`  | Cache key prefix                       |
-| `security.max-header-length` | `2048`  | Max user agent length (DoS protection) |
+| Key                          |  Default  | Description                                            |
+| :--------------------------- | :-------: | :----------------------------------------------------- |
+| `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 |
+| `security.max-header-length` |  `2048`   | Max user agent length (DoS protection)                 |
 
 ## Quality
 

config/browser-detect.php

@@ -10,6 +10,13 @@
          * Cache prefix, the user agent string will be hashed and appended at the end.
          */
         '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.
+         */
+        'device-detector' => false,
     ],
     'security' => [
         /**

src/Parser.php

@@ -81,7 +81,7 @@ public function __construct(?CacheManager $cache = null, ?Request $request = nul
 
         $this->pipeline = [
             new Stages\CrawlerDetect,
-            new Stages\DeviceDetector,
+            new Stages\DeviceDetector($this->cacheConfig()['device-detector']),
             new Stages\BrowserDetect,
         ];
     }
@@ -202,11 +202,11 @@ protected function makeHashKey(string $agent): string
     }
 
     /**
-     * @return array{interval: int, prefix: string}
+     * @return array{interval: int, prefix: string, device-detector: bool}
      */
     private function cacheConfig(): array
     {
-        /** @var array{interval: int, prefix: string} */
+        /** @var array{interval: int, prefix: string, device-detector: bool} */
         return $this->config['cache'];
     }
 

src/Stages/DeviceDetector.php

@@ -13,12 +13,17 @@ class DeviceDetector implements StageInterface
 {
     protected ?\DeviceDetector\DeviceDetector $detector = null;
 
+    public function __construct(protected bool $useDeviceDetectorCache = false) {}
+
     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());
+            }
         }
         $this->detector->setUserAgent($payload->getAgent());
         $this->detector->parse();

tests/Stages/DeviceDetectorTest.php

@@ -5,6 +5,7 @@
 use hisorange\BrowserDetect\Payload;
 use hisorange\BrowserDetect\Stages\DeviceDetector;
 use hisorange\BrowserDetect\Test\TestCase;
+use Illuminate\Support\Facades\Cache;
 use PHPUnit\Framework\Attributes\DataProvider;
 
 /**
@@ -77,6 +78,24 @@ public static function provideAgents()
         ];
     }
 
+    /**
+     * @covers ::__construct()
+     * @covers ::__invoke()
+     */
+    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);
+        $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);
+
+        $this->assertSame('Blink', $payload->getValue('browserEngine'));
+        $this->assertSame('Chrome', $payload->getValue('browserFamily'));
+        Cache::shouldHaveReceived('put');
+    }
+
     /**
      * @covers ::__invoke()
      */