device-detector

Introduction to DeviceDetector

DeviceDetector is a Universal Device Detection library developed under the matomo namespace. It is designed to parse User Agents and Browser Client Hints, allowing developers to effectively detect a variety of devices, clients, operating systems, brands, and models. From desktops to tablets, mobile phones, TVs, cars, and even game consoles, DeviceDetector can identify them all.

Features and Functionality

At its core, DeviceDetector can discern between numerous types of devices such as smartphones, tablets, and smart TVs. Additionally, it identifies client types like web browsers, media players, and mobile apps. The library does not stop at identifying devices; it also determines the operating system and browser family running on each device.

Usage

DeviceDetector is easy to implement in any PHP project. Developers can integrate it using Composer by installing the matomo/device-detector package. Usage involves creating an instance of DeviceDetector and feeding it User Agent strings, optionally supported by Client Hints.

Here's a brief illustration of how DeviceDetector can be utilized:

require_once 'vendor/autoload.php';

use DeviceDetector\DeviceDetector;

$userAgent = $_SERVER['HTTP_USER_AGENT'];
$dd = new DeviceDetector($userAgent);

$dd->parse();

if ($dd->isBot()) {
    // processes information for bots
    $botInfo = $dd->getBot();
} else {
    // process information for regular users
    $clientInfo = $dd->getClient();
    $osInfo = $dd->getOs();
    $device = $dd->getDeviceName();
    $brand = $dd->getBrandName();
    $model = $dd->getModel();
}

Advanced Options

The library allows several optional configurations to tailor its usage:

• Caching: In-memory array caching is the default setting for performance optimization. For persistent caching, developers can integrate file or memcached storage.

• Yaml Parser: While the default parser is Spyc, developers can swap it with other parsers like Symfony.

• Bot Handling: Developers can choose whether to retrieve extensive bot information or skip bot detection entirely.

Installation Without Composer

If not using Composer, DeviceDetector can be integrated using an autoloader. This approach, however, requires the manual inclusion of necessary dependencies like a YAML parser.

Caching Integration

Developers looking for enhanced caching can choose from various caching systems compliant with PSR-6 or PSR-16 such as Symfony's cache system or Matthias Mullie's Scrapbook. Integration with frameworks like Doctrine and Laravel is also possible.

Contribution and Community

DeviceDetector is open source, released under the LGPL v3 license. It welcomes community contributions, feedback, and pull requests. Developed by the Matomo team along with contributors like Stefan Giehl, Matthieu Aubry, and others, it aims to be the leading device detection library.

Cross-language Support

The DeviceDetector project has inspired ports to several programming languages including .NET, Ruby, JavaScript, Python, and more, ensuring that it meets the needs of developers working within different ecosystems.

Testing

To ensure robustness, DeviceDetector supports testing via PHPUnit among other testing tools, ensuring code quality and reliability.

In summary, DeviceDetector is a comprehensive and versatile tool for device recognition in PHP projects, supporting a broad range of devices and operating systems. With its extensive feature set and ease of integration, it is a valuable resource for developers looking to implement sophisticated user-agent parsing capabilities.