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.

New in 6.5.1: The release introduces improved bot detection (including Yandex bots, generic bots, and Google bot separation), new device/brand support (e.g., Vivaldi Mobile iOS, Apple iPhone 17e, HarmonyOS NEXT, Huawei MateBook Pro), and refined version detection for iOS, macOS, and Android. For basic use, 5–10 lines of code still suffice—no heavy configuration is 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). New in 6.5.1: Leverage improved bot detection (e.g., isBot() now better distinguishes Yandex bots and Google bots) to optimize webhook/endpoint processing.
• Bot filtering: In webhooks or form endpoints, run DeviceDetector early to skip processing for known bots ($dd->isBot()). The release enhances bot detection for Yandex, KT-Tech, and generic crawlers, reducing false positives.
• 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 browsers. New in 6.5.1: Fixed client hints type handling (PR #8281) for better compatibility with newer PHP/Symfony versions.
• Caching strategy: In high-traffic apps, inject a cache adapter early (e.g., new LaravelCache()). The YAML parser remains unchanged, but improved version detection (e.g., iOS/macOS/Android) may warrant recaching patterns if you rely on version-specific logic.
• Partial parsing: When only bot detection is needed, use BotParser directly or call $dd->skipBotDetection() and $dd->discardBotInformation() for speed. New in 6.5.1: Bot detection is now more granular (e.g., separate Google bots via PR #8251), so partial parsing may yield more precise results.
• OS/Browser families: Leverage OperatingSystem::getOsFamily() and Browser::getBrowserFamily() to normalize groups. New in 6.5.1: Version detection for iOS, macOS, and Android is refined (PRs #8260, #8263, #8268), so family-based logic may now capture more accurate versioning.
• New device/brand support: Use getBrandName() and getModel() to detect newly added devices (e.g., Vivaldi Mobile iOS, HarmonyOS NEXT). Example:

  if ($dd->getClient()->getBrowserFamily() === 'Vivaldi') {
      // Handle Vivaldi Mobile iOS (PR #8261)
  }
  

Gotchas and Tips

• Version truncation: By default, DeviceDetector returns truncated versions (e.g., 112 → 112.0). Use AbstractDeviceParser::setVersionTruncation(AbstractDeviceParser::VERSION_TRUNCATION_NONE) if full versions are needed—but benchmark impact, especially with iOS/macOS/Android improvements in 6.5.1.
• YAML parser dependency: Ensure symfony/yaml or spyc is installed. New in 6.5.1: The package now supports Symfony 7.x (PR #8273), so update dependencies if using newer Symfony versions.
• Cache key collisions: The static cache is per-request only. If using multiple DeviceDetector instances (e.g., for bot-skip vs full-mode), manually invalidate or use distinct keys. New in 6.5.1: Improved bot detection may change cache keys for bot-related requests.
• Client Hints mismatch: Validate ClientHints::factory($_SERVER) returns non-null. Fixed in 6.5.1: Client hints type handling is now more robust (PR #8281).
• False positives in bots: The bot list is exhaustive but may still flag rare tools. Use discardBotInformation() for performance or whitelist known bots. New in 6.5.1: Yandex and Google bots are now separately detected (PRs #8237, #8251), reducing false positives.
• Custom user agents: Sanitize AGENT strings to avoid inconsistent results. Passing null or malformed UA causes issues—validate first.
• Laravel integration tip: Bind a shared DeviceDetector instance in ServiceProvider and cache it via Cache::remember(). New in 6.5.1: With refined version detection, cached results may need updating if you rely on version-specific logic.
• New devices/brands: Test edge cases for newly supported devices (e.g., HarmonyOS NEXT, Apple iPhone 17e). Example:

  if ($dd->getOs()->getName() === 'HarmonyOS') {
      // Handle HarmonyOS NEXT (PR #8279)
  }
  

• PHPUnit 13 support: Updated in 6.5.1 (PR #8257). If using PHPUnit 13+, no action is needed.
• Edge cases: The release adds Headless Edge detection (PR #8278). Test if your app interacts with headless browsers.