Device Detector

Device Detector is a PHP library, built by the Matomo team, that parses any User Agent string or Client Hints payload and identifies the browser, operating system, device type (desktop, tablet, mobile, TV, console, car, wearable, and more), brand, and model. It ships with an extensive, community-maintained set of YAML regex definitions covering thousands of clients and devices, and is used in production by Matomo Analytics as well as many other PHP projects that need reliable, self-hosted device detection without calling an external API.

Beyond simple detection, it exposes granular helper methods (isSmartphone, isBot, isTV, and dozens more) and supports pluggable caching backends (PSR-6, PSR-16, Doctrine, Laravel) so repeated lookups in high-traffic applications stay fast. Because everything runs locally against bundled regex data, there are no external API calls, rate limits, or per-request costs, which makes it a popular choice for privacy-conscious analytics and bot-detection pipelines.

What You Get

• A DeviceDetector class that parses a user agent string plus optional Client Hints into browser, OS, device, and bot information
• Dozens of is*() helper methods (isSmartphone, isBot, isTV, isCarBrowser, isWearable, etc.) for quick type checks
• An extensive, continuously updated set of YAML regex definitions covering thousands of browsers, bots, apps, and devices
• Pluggable caching adapters (static array, PSR-6, PSR-16, Doctrine, Laravel) to avoid re-parsing identical user agents
• A standalone Bot parser for lightweight bot detection when full device parsing isn’t needed

Common Use Cases

• Self-hosted analytics platforms that need to classify visitor devices/browsers without sending data to a third-party API
• Bot and crawler filtering in access logs or request middleware before they hit application logic
• Serving device-tailored content or redirects (e.g. mobile app deep links) based on detected device type
• Enriching server-side logs or BI pipelines with structured client/device metadata

Under The Hood

Architecture: The library centers on a DeviceDetector orchestrator (DeviceDetector.php) that runs a user agent string (plus optional ClientHints) through a pipeline of parsers under Parser/ — Parser\Bot, Parser\Client\* (browsers, media players, feed readers), Parser\Device\* (brand/model detection per device family), and Parser\OperatingSystem — each backed by regex definitions loaded from YAML files under regexes/. Parsing short-circuits on bot detection, then walks device/client parsers until a match is found, giving a clear separation between matching logic (PHP) and detection data (YAML).

Tech Stack: Pure PHP (^7.2 or ^8.0) with a Spyc-based YAML parser by default, swappable for Symfony’s YAML component or the PECL yaml extension. Dependency footprint is minimal; caching integrates via PSR-6/PSR-16 interfaces plus bundled bridges for Doctrine and Laravel caches rather than bundling a cache implementation itself.

Code Quality: The Tests/ directory mirrors the Parser/ structure with fixture-driven unit tests (DeviceDetectorTest.php, ClientHintsTest.php, per-parser fixtures) run via PHPUnit, plus PHPStan static analysis and a dedicated coding-standard/CI workflow (PHPCS, YAML lint, regex validation) enforced on every push, reflecting the project’s role as a dependency of Matomo’s core analytics pipeline.

API Design: The public surface is a small set of well-named methods (parse(), isBot(), getClient(), getOs(), getDeviceName()) plus a long list of explicit is*() type checks, making common queries self-documenting; getting started requires only instantiating DeviceDetector with a user agent string and calling parse(), with caching and custom YAML parsers as optional configuration steps.