feat: use utopia-php/user-agent for user-agent parsing

Rewrites Appwrite\Detector\Detector to wrap utopia-php/user-agent instead
of matomo/device-detector. The public shape (getOS/getClient/getDevice/
skipBotDetection) is unchanged, so the four call sites are untouched. The
AppwriteCLI short-circuit and the ''-vs-null defaults (os/client default to
'', device fields to null) are preserved.

matomo/device-detector is removed from composer — it was used only through
this wrapper, and isBot() was never called anywhere. utopia-php/user-agent
requires PHP >=8.4, already satisfied by the >=8.5 floor on main.

utopia 0.1.1 keeps Matomo-aligned short codes, so parsing is byte-identical
for the tested user agents (Firefox 47 unit test; Chrome 70 and Chrome
Mobile e2e session and webhook assertions). Expands DetectorTest with the
AppwriteCLI branch, a mobile client, and the unknown-user-agent defaults.
This commit is contained in:
Damodar Lohani committed 2026-07-21 08:56:33 +05:45
1 parent eab4e9faee
commit 661aa8124e
4 files changed
+130 -181

No files matched your search

+1 -1
View File
@@ -94,9 +94,9 @@
"utopia-php/storage": "2.*",
"utopia-php/system": "0.10.*",
"utopia-php/telemetry": "^0.4",
"utopia-php/user-agent": "0.1.*",
"utopia-php/vcs": "^4.4.2",
"utopia-php/websocket": "1.0.*",
"matomo/device-detector": "6.4.*",
"dragonmantank/cron-expression": "3.4.*",
"phpmailer/phpmailer": "6.9.*",
"chillerlan/php-qrcode": "4.3.*",
Generated
+43 -125
View File
@@ -4,7 +4,7 @@
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "f1d913d8ccc683139c24d76d7d697e97",
"content-hash": "38ff4f69a268151556ee8776b1afab39",
"packages": [
{
"name": "adhocore/jwt",
@@ -800,76 +800,6 @@
],
"time": "2023-12-29T07:34:53+00:00"
},
{
"name": "matomo/device-detector",
"version": "6.4.8",
"source": {
"type": "git",
"url": "https://github.com/matomo-org/device-detector.git",
"reference": "56baf981af4f192e15a4f369d4975af847a81ccb"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/matomo-org/device-detector/zipball/56baf981af4f192e15a4f369d4975af847a81ccb",
"reference": "56baf981af4f192e15a4f369d4975af847a81ccb",
"shasum": ""
},
"require": {
"mustangostang/spyc": "*",
"php": "^7.2|^8.0"
},
"replace": {
"piwik/device-detector": "self.version"
},
"require-dev": {
"matthiasmullie/scrapbook": "^1.4.7",
"mayflower/mo4-coding-standard": "^v9.0.0",
"phpstan/phpstan": "^1.10.44",
"phpunit/phpunit": "^8.5.8",
"psr/cache": "^1.0.1",
"psr/simple-cache": "^1.0.1",
"slevomat/coding-standard": "<8.16.0",
"symfony/yaml": "^5.1.7"
},
"suggest": {
"doctrine/cache": "Can directly be used for caching purpose",
"ext-yaml": "Necessary for using the Pecl YAML parser"
},
"type": "library",
"autoload": {
"psr-4": {
"DeviceDetector\\": ""
},
"exclude-from-classmap": [
"Tests/"
]
},
"notification-url": "https://packagist.org/downloads/",
"license": [
"LGPL-3.0-or-later"
],
"authors": [
{
"name": "The Matomo Team",
"email": "hello@matomo.org",
"homepage": "https://matomo.org/team/"
}
],
"description": "The Universal Device Detection library, that parses User Agents and detects devices (desktop, tablet, mobile, tv, cars, console, etc.), clients (browsers, media players, mobile apps, feed readers, libraries, etc), operating systems, devices, brands and models.",
"homepage": "https://matomo.org",
"keywords": [
"devicedetection",
"parser",
"useragent"
],
"support": {
"forum": "https://forum.matomo.org/",
"issues": "https://github.com/matomo-org/device-detector/issues",
"source": "https://github.com/matomo-org/matomo",
"wiki": "https://dev.matomo.org/"
},
"time": "2025-11-26T16:02:47+00:00"
},
{
"name": "mongodb/mongodb",
"version": "2.1.2",
@@ -947,60 +877,6 @@
},
"time": "2025-10-06T12:12:40+00:00"
},
{
"name": "mustangostang/spyc",
"version": "0.6.3",
"source": {
"type": "git",
"url": "https://github.com/mustangostang/spyc.git",
"reference": "4627c838b16550b666d15aeae1e5289dd5b77da0"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/mustangostang/spyc/zipball/4627c838b16550b666d15aeae1e5289dd5b77da0",
"reference": "4627c838b16550b666d15aeae1e5289dd5b77da0",
"shasum": ""
},
"require": {
"php": ">=5.3.1"
},
"require-dev": {
"phpunit/phpunit": "4.3.*@dev"
},
"type": "library",
"extra": {
"branch-alias": {
"dev-master": "0.5.x-dev"
}
},
"autoload": {
"files": [
"Spyc.php"
]
},
"notification-url": "https://packagist.org/downloads/",
"license": [
"MIT"
],
"authors": [
{
"name": "mustangostang",
"email": "vlad.andersen@gmail.com"
}
],
"description": "A simple YAML loader/dumper class for PHP",
"homepage": "https://github.com/mustangostang/spyc/",
"keywords": [
"spyc",
"yaml",
"yml"
],
"support": {
"issues": "https://github.com/mustangostang/spyc/issues",
"source": "https://github.com/mustangostang/spyc/tree/0.6.3"
},
"time": "2019-09-10T13:16:29+00:00"
},
{
"name": "nyholm/psr7",
"version": "1.8.2",
@@ -5152,6 +5028,48 @@
},
"time": "2026-07-08T11:07:25+00:00"
},
{
"name": "utopia-php/user-agent",
"version": "0.1.1",
"source": {
"type": "git",
"url": "https://github.com/utopia-php/user-agent.git",
"reference": "4f7bb7288cfe3ce8e257944c0827914901c873bc"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/utopia-php/user-agent/zipball/4f7bb7288cfe3ce8e257944c0827914901c873bc",
"reference": "4f7bb7288cfe3ce8e257944c0827914901c873bc",
"shasum": ""
},
"require": {
"php": ">=8.4"
},
"require-dev": {
"matomo/device-detector": "6.4.*"
},
"type": "library",
"autoload": {
"psr-4": {
"Utopia\\UserAgent\\": "src/UserAgent/"
}
},
"notification-url": "https://packagist.org/downloads/",
"license": [
"MIT"
],
"description": "A fast user-agent parser and device detector for PHP",
"keywords": [
"device-detection",
"parser",
"user-agent"
],
"support": {
"issues": "https://github.com/utopia-php/user-agent/issues",
"source": "https://github.com/utopia-php/user-agent/tree/0.1.1"
},
"time": "2026-07-20T09:05:28+00:00"
},
{
"name": "utopia-php/validators",
"version": "0.3.0",
+45 -55
View File
@@ -2,17 +2,14 @@
namespace Appwrite\Detector;
use DeviceDetector\DeviceDetector;
use Utopia\UserAgent\UserAgent;
class Detector
{
protected $userAgent = '';
protected string $userAgent;
protected $detctor;
protected ?UserAgent $agent = null;
/**
* @param string $userAgent
*/
public function __construct(string $userAgent)
{
$this->userAgent = $userAgent;
@@ -21,90 +18,83 @@ class Detector
/**
* Get OS info
*
* @return array
* @return array<string, string>
*/
public function getOS(): array
{
$os = $this->getDetector()->getOs();
$os = $this->getAgent()->operatingSystem();
return [
'osCode' => (isset($os['short_name'])) ? $os['short_name'] : '',
'osName' => (isset($os['name'])) ? $os['name'] : '',
'osVersion' => (isset($os['version'])) ? $os['version'] : '',
'osCode' => $os->code ?? '',
'osName' => $os->name ?? '',
'osVersion' => $os->version ?? '',
];
}
/**
* Get client info
*
* @return array
* @return array<string, string>
*/
public function getClient(): array
{
if (strpos($this->userAgent, 'AppwriteCLI') !== false) {
$version = explode(' ', $this->userAgent)[0];
$version = explode('/', $version)[1];
$client = [
'type' => 'desktop',
'short_name' => 'cli',
'name' => 'Appwrite CLI',
'version' => $version
// The CLI is not a known user agent, so it is resolved manually
if (\str_contains($this->userAgent, 'AppwriteCLI')) {
$version = \explode(' ', $this->userAgent)[0];
$version = \explode('/', $version)[1] ?? '';
return [
'clientType' => 'desktop',
'clientCode' => 'cli',
'clientName' => 'Appwrite CLI',
'clientVersion' => $version,
'clientEngine' => '',
'clientEngineVersion' => '',
];
} else {
$client = $this->getDetector()->getClient();
}
$client = $this->getAgent()->client();
return [
'clientType' => (isset($client['type'])) ? $client['type'] : '',
'clientCode' => (isset($client['short_name'])) ? $client['short_name'] : '',
'clientName' => (isset($client['name'])) ? $client['name'] : '',
'clientVersion' => (isset($client['version'])) ? $client['version'] : '',
'clientEngine' => (isset($client['engine'])) ? $client['engine'] : '',
'clientEngineVersion' => (isset($client['engine_version'])) ? $client['engine_version'] : '',
'clientType' => $client->type ?? '',
'clientCode' => $client->code ?? '',
'clientName' => $client->name ?? '',
'clientVersion' => $client->version ?? '',
'clientEngine' => $client->engine ?? '',
'clientEngineVersion' => $client->engineVersion ?? '',
];
}
/**
* Get device info
*
* @return array
* @return array<string, string|null>
*/
public function getDevice(): array
{
$deviceName = $this->getDetector()->getDeviceName();
$deviceBrand = $this->getDetector()->getBrandName();
$deviceModel = $this->getDetector()->getModel();
$device = $this->getAgent()->device();
return [
'deviceName' => empty($deviceName) ? null : $deviceName,
'deviceBrand' => empty($deviceBrand) ? null : $deviceBrand,
'deviceModel' => empty($deviceModel) ? null : $deviceModel,
'deviceName' => empty($device->type) ? null : $device->type,
'deviceBrand' => empty($device->brand) ? null : $device->brand,
'deviceModel' => empty($device->model) ? null : $device->model,
];
}
/**
* @return DeviceDetector
*/
protected function getDetector(): DeviceDetector
{
if (!$this->detctor) {
$this->detctor = new DeviceDetector($this->userAgent);
$this->detctor->skipBotDetection(); // OPTIONAL: If called, bot detection will completely be skipped (bots will be detected as regular devices then)
$this->detctor->parse();
}
return $this->detctor;
}
/**
* Sets whether to skip bot detection.
* It is needed if we want bots to be processed as a simple clients. So we can detect if it is mobile client,
* or desktop, or enything else. By default all this information is not retrieved for the bots.
*
* @param bool $skip
* No-op kept for call site compatibility. utopia-php/user-agent never suppresses
* OS, client or device info for bots, so there is nothing to skip.
*/
public function skipBotDetection(bool $skip = true): void
{
$this->getDetector()->skipBotDetection($skip);
}
protected function getAgent(): UserAgent
{
if ($this->agent === null) {
$this->agent = UserAgent::parse($this->userAgent);
}
return $this->agent;
}
}
+41
View File
@@ -49,4 +49,45 @@ final class DetectorTest extends TestCase
'deviceModel' => '',
]);
}
public function testMobileClient(): void
{
$detector = new Detector('Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1');
$this->assertEquals(['osCode' => 'IOS', 'osName' => 'iOS', 'osVersion' => '17.0'], $detector->getOS());
$this->assertEquals('MF', $detector->getClient()['clientCode']);
$this->assertEquals([
'deviceName' => 'smartphone',
'deviceBrand' => 'Apple',
'deviceModel' => 'iPhone',
], $detector->getDevice());
}
public function testCliClient(): void
{
$detector = new Detector('AppwriteCLI/2.0.0 (linux; x64) node/18.0.0');
$this->assertEquals([
'clientType' => 'desktop',
'clientCode' => 'cli',
'clientName' => 'Appwrite CLI',
'clientVersion' => '2.0.0',
'clientEngine' => '',
'clientEngineVersion' => '',
], $detector->getClient());
}
public function testUnknownUserAgent(): void
{
$detector = new Detector('');
// OS and client fields default to an empty string, device fields to null.
$this->assertEquals(['osCode' => '', 'osName' => '', 'osVersion' => ''], $detector->getOS());
$this->assertEquals('', $detector->getClient()['clientType']);
$this->assertEquals([
'deviceName' => null,
'deviceBrand' => null,
'deviceModel' => null,
], $detector->getDevice());
}
}