PHPackages                             jooservices/useragent - 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. [Utility & Helpers](/categories/utility)
4. /
5. jooservices/useragent

ActiveLibrary[Utility & Helpers](/categories/utility)

jooservices/useragent
=====================

Advanced User-Agent string generator with flexible randomization strategies

1.2.0(2mo ago)010MITPHPPHP ^8.5

Since Jan 29Pushed 2mo agoCompare

[ Source](https://github.com/jooservices/useragent)[ Packagist](https://packagist.org/packages/jooservices/useragent)[ RSS](/packages/jooservices-useragent/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (3)Dependencies (20)Versions (5)Used By (0)

UserAgent Library
=================

[](#useragent-library)

A powerful, comprehensive PHP library for generating realistic, specification-compliant User-Agent strings.

Features
--------

[](#features)

- **Realistic Generation**: Generates authentic User-Agents for Chrome, Firefox, Safari, and Edge.
- **Specification System**: Fluent builder API to define exact requirements (device, OS, version, etc.).
- **Smart Pickers**: Intelligent selection of versions, models, locales, and architectures based on platform validity.
- **Strategies**: Multiple selection strategies (Uniform, Weighted Market Share, Round Robin, Avoid Recent).
- **Profiles**: Pre-configured shortcuts for common profiles (Desktop Chrome, Mobile Safari, etc.).
- **Deterministic**: Seed-based generation for reproducible testing.
- **High Quality**: 100% Type-safe, PHPStan Level 9, 99% Test Coverage.

Documentation
-------------

[](#documentation)

- **[Documentation Hub](docs/README.md)**: Canonical entrypoint for usage, architecture, flows, and reference docs.
- **[Usage Guide](docs/usage.md)**: Full documentation on generation, strategies, and shortcuts.
- **[Examples](docs/examples/)**: Runnable scripts demonstrating all features.
- **[Contributing](CONTRIBUTING.md)**: Guide for contributors.
- **[Security](SECURITY.md)**: Vulnerability reporting policy.

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

[](#installation)

```
composer require jooservices/useragent
```

CLI Usage
---------

[](#cli-usage)

The library includes a zero-dependency CLI tool for generating strings from the command line.

```
# Generate 1 random string
./vendor/bin/useragent

# Generate 5 strings
./vendor/bin/useragent --count=5

# Specific constraints
./vendor/bin/useragent --browser=firefox --os=windows
./vendor/bin/useragent --device=mobile --browser=safari
```

Quick Start
-----------

[](#quick-start)

### Static Facade (Recommended)

[](#static-facade-recommended)

The easiest way to generate a User-Agent string is via the fluent static API:

```
use JOOservices\UserAgent\UserAgent;

// Simple random generation
echo UserAgent::generate();

// Fluent Chaining
echo UserAgent::chrome()->windows()->generate();
echo UserAgent::firefox()->linux()->generate();
echo UserAgent::safari()->mobile()->generate();

// Unique Generation (Guarantees no duplicates in a loop)
$ua = UserAgent::unique()->generate();

// Exclusion (Invert selection)
// After exclude(), every following constraint in the chain is an exclusion.
// Example: "Give me anything EXCEPT Mobile" → desktop or tablet only
echo UserAgent::exclude()->mobile()->generate();
// Example: Chrome but NOT mobile → Chrome on desktop or tablet
echo UserAgent::chrome()->exclude()->mobile()->generate();
```

### Legacy / Service Usage

[](#legacy--service-usage)

```
use JOOservices\UserAgent\Service\UserAgentService;

$service = new UserAgentService();
$ua = $service->generate();

echo $ua;
// Output option: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
```

### Using Profiles (Shortcuts)

[](#using-profiles-shortcuts)

Use pre-defined profiles for common scenarios:

```
use JOOservices\UserAgent\Service\Profiles\Profiles;

$profiles = new Profiles($service);

// Desktop Chrome on Windows
echo $profiles->desktopChrome->windows();

// iPhone Safari
echo $profiles->mobileSafari->iphone();

// Android Chrome
echo $profiles->androidChrome->phone();

// Random Mobile Device
echo $profiles->randomMobile();
```

### Advanced Specification

[](#advanced-specification)

Use the builder API for precise control:

```
use JOOservices\UserAgent\Domain\Enums\BrowserFamily;
use JOOservices\UserAgent\Domain\Enums\DeviceType;
use JOOservices\UserAgent\Domain\Enums\OperatingSystem;
use JOOservices\UserAgent\Spec\GenerationSpec;

$spec = GenerationSpec::create()
    ->browser(BrowserFamily::Chrome)
    ->device(DeviceType::Mobile)
    ->os(OperatingSystem::Android)
    ->versionMin(100)
    ->locale('fr-FR')
    ->build();

$ua = $service->generate($spec);
```

Runtime currently enforces: `browser`, `device`, `os`, `engine`, `riskLevel`, `version*`, `locale`, `arch`, `strategy`. The fields `channel`, `tags`, `weights`, and `randomSpec` are validated but intentionally rejected during generation until full runtime support lands.

### Deterministic Generation (For Tests)

[](#deterministic-generation-for-tests)

Pass a seed to generate the exact same UA every time:

```
$seed = 12345;
$ua1 = $service->generate($spec, seed: $seed);
$ua2 = $service->generate($spec, seed: $seed);

assert($ua1 === $ua2); // True
```

Architecture
------------

[](#architecture)

- **Service Layer**: `UserAgentService` orchestrates the generation process.
- **Pickers**: specialized logic for selecting `Version`, `Model`, `Locale`, and `Arch`.
- **Templates**: Browser-specific templates (Chrome, Firefox, Safari, Edge) with device/OS awareness.
- **Filters**: System to filter valid templates based on constraints.
- **History**: `LruHistory` prevents repeating recently generated UAs.

Compatibility
-------------

[](#compatibility)

ScopeSupported**Browsers**Chrome, Firefox, Safari, Edge**OS**Windows, macOS, Linux, Android, iOS, ChromeOS**Device types**Desktop, Mobile, Tablet**Notable invalid combinations**Safari + Windows, Safari + Linux, Safari + Android; Edge + Linux (desktop); Safari desktop = macOS only, Safari mobile = iOS only**CLI → spec**`--browser` → browser, `--device` → device, `--os` → os, `--count` → batch size, `--unique` → dedupe, `--format` → output (text/json/csv)Use `UserAgent::supportedCombinations()->getValidCombinations()` to list all valid (browser, device, OS) pairs.

Use-case recipes
----------------

[](#use-case-recipes)

GoalAPI100 unique mobile UAs for scraper rotation`UserAgent::batch(100, ['spec' => UserAgent::scenarioPresetMobileFirstApac(), 'unique' => true])` or `UserAgent::mobile()->unique()` + loop `generate()`Deterministic UA for PHPUnit`UserAgent::seed(12345);` then `UserAgent::chrome()->windows()->generate()`Exclude Safari`UserAgent::exclude()->safari()->generate()` (after `exclude()`, all following constraints are exclusions)Start chain with no constraint`UserAgent::builder()->locale('fr-FR')->generate()`Same constraints, N UAs`UserAgent::chrome()->windows()->generateMany(5)` or `UserAgent::batch(5, ['spec' => UserAgent::chrome()->windows()->toSpec()])`Weighted real-market traffic`UserAgent::generate()` or `UserAgent::batch(N, ['unique' => false])`Browser matrix for QA`UserAgent::scenarioPresetQaBrowserMatrix()` then `$service->generate($spec)` per specSee [Usage guide](docs/usage.md#use-case-recipes) for full examples.

Requirements
------------

[](#requirements)

- PHP 8.5+
- `random_int()` support

License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance86

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~19 days

Total

3

Last Release

71d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/142772948?v=4)[JOOservices Ltd](/maintainers/jooservices)[@jooservices](https://github.com/jooservices)

---

Top Contributors

[![soulevilx](https://avatars.githubusercontent.com/u/2688707?v=4)](https://github.com/soulevilx "soulevilx (30 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/jooservices-useragent/health.svg)

```
[![Health](https://phpackages.com/badges/jooservices-useragent/health.svg)](https://phpackages.com/packages/jooservices-useragent)
```

###  Alternatives

[crwlr/crawler

Web crawling and scraping library.

37214.8k2](/packages/crwlr-crawler)

PHPackages © 2026

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