PHPackages                             utopia-php/user-agent - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. utopia-php/user-agent

ActiveLibrary[Parsing & Serialization](/categories/parsing)

utopia-php/user-agent
=====================

A fast user-agent parser and device detector for PHP

0.1.1(1mo ago)020.4k↑6236.4%MITPHPPHP >=8.4

Since Jul 17Pushed 1mo agoCompare

[ Source](https://github.com/utopia-php/user-agent)[ Packagist](https://packagist.org/packages/utopia-php/user-agent)[ RSS](/packages/utopia-php-user-agent/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (2)Versions (3)Used By (0)

Utopia User Agent
=================

[](#utopia-user-agent)

Important

This repository is a read-only mirror of the [utopia-php monorepo](https://github.com/utopia-php/monorepo). Development happens in [`packages/user-agent`](https://github.com/utopia-php/monorepo/tree/main/packages/user-agent) — please open issues and pull requests there.

A fast user-agent parser and device detector for PHP.

Utopia User Agent provides typed operating-system, client, device, and bot results without runtime data files or dependencies. Detection categories are lazy and memoized: asking only for a device does not run browser or bot rules.

Installation
------------

[](#installation)

```
composer require utopia-php/user-agent
```

Quick start
-----------

[](#quick-start)

```
use Utopia\UserAgent\UserAgent;

$agent = UserAgent::parse($_SERVER['HTTP_USER_AGENT'] ?? '');

$os = $agent->operatingSystem();
$client = $agent->client();
$device = $agent->device();

echo $os->name;       // iOS
echo $client->name;   // Mobile Safari
echo $device->type;   // smartphone
echo $device->brand;  // Apple
echo $device->model;  // iPhone

if ($agent->isBot()) {
    echo $agent->bot()?->name;
}
```

Results
-------

[](#results)

Every category returns a value object. Unknown fields are `null`, so malformed, empty, and unfamiliar user-agent strings are safe to inspect without exception handling.

### Operating system

[](#operating-system)

```
$os = $agent->operatingSystem();

$os->code;       // ?string, for example IOS, AND, WIN, MAC
$os->name;       // ?string
$os->version;    // ?string
$os->isKnown();  // bool
```

### Client

[](#client)

```
$client = $agent->client();

$client->type;           // ?string: browser, library, desktop, ...
$client->code;           // ?string
$client->name;           // ?string
$client->version;        // ?string
$client->engine;         // ?string
$client->engineVersion;  // ?string
$client->isBrowser();    // bool
```

### Device

[](#device)

```
$device = $agent->device();

$device->type;      // ?string: desktop, smartphone, tablet, tv, console, ...
$device->brand;     // ?string
$device->model;     // ?string
$device->isKnown(); // bool
```

`Device::$type` represents the device class rather than its model name.

### Bot

[](#bot)

Bot detection is independent from the other categories. A bot user-agent can still return its browser, OS, and device information.

```
if ($agent->isBot()) {
    $agent->bot()?->name;      // Googlebot
    $agent->bot()?->category;  // search crawler
}
```

### Serialization

[](#serialization)

Each value object has a `toArray()` method. The complete nested result is also available:

```
$data = $agent->toArray();

// [
//     'os' => ['code' => ..., 'name' => ..., 'version' => ...],
//     'client' => [...],
//     'device' => [...],
//     'bot' => null|['name' => ..., 'category' => ...],
// ]
```

Detection coverage
------------------

[](#detection-coverage)

The rule set covers common user agents:

- Windows, Windows Phone, macOS, iOS, iPadOS, tvOS, watchOS, Android, Fire OS, Chrome OS, HarmonyOS, webOS, Sailfish, Tizen, KaiOS, BlackBerry, PlayStation, Nintendo, and popular Linux distributions (Ubuntu, Debian, Fedora, Arch Linux, Mint, and more)
- Chrome, Safari, Firefox, Edge, Opera, Opera Mobile, Samsung Internet, Brave, Vivaldi, Yandex Browser, UC Browser, DuckDuckGo, QQ Browser, Coc Coc, Whale, Huawei Browser, Amazon Silk, Firefox Focus, Android WebView, Internet Explorer, and their common mobile variants
- Common HTTP libraries (curl, Wget, OkHttp, Guzzle, Python Requests, aiohttp, Go-http-client, Node Fetch, Axios, Java, HTTPie, and more)
- Desktop, smartphone, tablet, TV, console, wearable, and portable-media device classes with common device brands and models
- Search, social-preview, monitoring, automation, SEO, and AI crawlers (including GPTBot, ClaudeBot, PerplexityBot, Google Extended, and other large-language-model agents)

Core result fields are regression-tested against Matomo DeviceDetector 6.4 for representative profiles. The runtime does not contain or load Matomo's LGPL rule data.

Performance
-----------

[](#performance)

The hot path uses direct token checks and a small bounded set of regular expressions. There are no YAML files, runtime rule compilation, global caches, or third-party runtime dependencies.

Run the bundled comparison benchmark:

```
composer bench
```

`BENCH_ITERATIONS` controls its duration. Matomo DeviceDetector is installed only as a development dependency for differential tests and benchmarks.

There is no `skipBotDetection()` setting. Bot matching runs only when `bot()`or `isBot()` is requested and never prevents the other categories from being detected.

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance91

Actively maintained with recent releases

Popularity30

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

2

Last Release

43d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/22452787?v=4)[Luke B. Silver](/maintainers/loks0n)[@loks0n](https://github.com/loks0n)

---

Top Contributors

[![lohanidamodar](https://avatars.githubusercontent.com/u/6360216?v=4)](https://github.com/lohanidamodar "lohanidamodar (1 commits)")[![loks0n](https://avatars.githubusercontent.com/u/22452787?v=4)](https://github.com/loks0n "loks0n (1 commits)")

---

Tags

parseruser agentDevice detection

### Embed Badge

![Health badge](/badges/utopia-php-user-agent/health.svg)

```
[![Health](https://phpackages.com/badges/utopia-php-user-agent/health.svg)](https://phpackages.com/packages/utopia-php-user-agent)
```

###  Alternatives

[nikic/php-parser

A PHP parser written in PHP

17.5k992.9M2.9k](/packages/nikic-php-parser)[doctrine/lexer

PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.

11.1k980.3M182](/packages/doctrine-lexer)[erusev/parsedown

Parser for Markdown.

15.1k160.1M957](/packages/erusev-parsedown)[league/commonmark

Highly-extensible PHP Markdown parser which fully supports the CommonMark spec and GitHub-Flavored Markdown (GFM)

3.0k464.7M1.3k](/packages/league-commonmark)[masterminds/html5

An HTML5 parser and serializer.

1.8k291.1M383](/packages/masterminds-html5)[sabberworm/php-css-parser

Parser for CSS Files written in PHP

1.8k227.1M82](/packages/sabberworm-php-css-parser)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)