Device Detector Laravel Package

Getting Started

Begin by installing the package via Composer: composer require matomo/device-detector. The core class is DeviceDetector, which accepts a user agent string (typically $_SERVER['HTTP_USER_AGENT']) and optional client hints (via ClientHints::factory($_SERVER)). After instantiation, call parse(), then use methods like isBot(), getDeviceName(), getOs(), getClient(), getBrandName(), and getModel() to extract details. For basic use, 5–10 lines of code suffice—no heavy configuration needed. Start by handling bots separately (isBot()) and fallback UI/UX based on device type (e.g., isTablet() vs isSmartphone()).

Implementation Patterns

• Per-request detection: Use in middleware or service classes to tailor responses (e.g., redirect mobile users, serve device-specific templates, or adjust analytics event names).
• Bot filtering: In webhooks or form endpoints, run DeviceDetector early to skip processing for known bots ($dd->isBot()), reducing load.
• Client Hints optimization: Configure Accept-CH headers (e.g., User-Agent, Device-Memory, Sec-CH-UA-Platform) to improve accuracy—especially for Android 13+ devices and modern Chrome/Firefox browsers.
• Caching strategy: In high-traffic apps, inject a cache adapter early: new LaravelCache() for Laravel or new PSR16Bridge(new SimpleCache(...)) for generic setups—crucial because YAML pattern matching is expensive on every request.
• Partial parsing: When only bot detection is needed, skip overhead by using BotParser directly (or call $dd->skipBotDetection() and $dd->discardBotInformation() for speed).
• OS/Browser families: Leverage OperatingSystem::getOsFamily() and Browser::getBrowserFamily() to normalize version-agnostic groups (e.g., group all Firefox variants under “Firefox”).

Gotchas and Tips

• Version truncation: By default, DeviceDetector returns truncated versions (e.g., 112 → 112.0). Use AbstractDeviceParser::setVersionTruncation(AbstractDeviceParser::VERSION_TRUNCATION_NONE) if you need full version numbers—but benchmark impact on memory/cache size.
• YAML parser dependency: DeviceDetector doesn’t auto-install a YAML parser. Ensure symfony/yaml or spyc is available; otherwise, parsing silently fails or throws. Prefer symfony/yaml for reliability and ongoing support.
• Cache key collisions: The static cache is per-request only. If you use multiple DeviceDetector instances with different configs (e.g., bot-skip vs full-mode), manually invalidate or use distinct cache keys.
• Client Hints mismatch: If Accept-CH headers aren’t set server-side, client hints may be missing entirely—even on modern browsers. Validate ClientHints::factory($_SERVER) returns non-null before relying on it.
• False positives in bots: The built-in bot list is exhaustive but may flag rare legitimate tools. Use discardBotInformation() for performance-critical paths, or whitelist known bots after initial analysis.
• Custom user agents: Always sanitize/unify AGENT strings—especially from internal services or legacy systems. Passing null or malformed UA causes inconsistent results; validate first.
• Laravel integration tip: Extend ServiceProvider to bind a shared DeviceDetector instance, and cache it via Cache::remember() in your controller to avoid repeated instantiation and YAML parsing across requests.