jooservices/jooagent

Generate random user agent

1.0.0 2025-11-08 06:33 UTC

Requires

• php: ^8.4

Requires (Dev)

• laravel/pint: ^1.17
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^1.11
• phpunit/phpunit: 12.*
• squizlabs/php_codesniffer: ^3.10

Suggests

• ext-mongodb: Required for MongoDB logging driver
• ext-redis: Required for Redis cache driver

proprietary

• Viet Vu

README

Generate realistic user agent strings with SOLID-friendly components and configurable catalogs.

Features

• Build user agent strings by selecting operating system, device, browser, and versions.
• Fluent builder API (UserAgentBuilder) for chainable configuration or random defaults.
• Specification + repository design for substituting storage backends.
• Automatic version resolution with explicit version, semantic constraints, or random selection.
• Tag-based filtering (desktop, mobile, bot, console, etc.).
• Pluggable definition providers (in-memory defaults, JSON catalogs, custom implementations).
• CLI to refresh browser versions from browsers.fyi.
• Desktop session helper ensures retries reuse the same desktop user agent.
• Comprehensive test suite (vendor/bin/phpunit).

Installation

composer require jooservices/jooagent

Requires PHP 8.4+

Quick Start

use JOOservices\Client\Dto\UserAgentSpecification;
use JOOservices\Client\Generators\UserAgentGeneratorFactory;

$generator = UserAgentGeneratorFactory::createDefault();

$specification = new UserAgentSpecification(
    operatingSystem: 'windows',
    device: 'desktop',
    browser: 'chrome',
    operatingSystemVersion: '11.0',
    browserVersion: '122.0.6261.111'
);

$userAgent = $generator->generate($specification);

echo $userAgent->value();

Or use the builder:

use JOOservices\Client\Builders\UserAgentBuilder;

$agent = UserAgentBuilder::create()
    ->operatingSystem('macos')
    ->device('desktop')
    ->browser('safari')
    ->browserVersionRange('>=17.0')
    ->generate();

echo $agent;

Desktop Request Sessions

Use DesktopUserAgentSession when you need a random desktop user agent per request, but the same value across retries:

use JOOservices\Client\Services\DesktopUserAgentSession;
use JOOservices\Client\Generators\UserAgentGeneratorFactory;

$session = new DesktopUserAgentSession(UserAgentGeneratorFactory::createDefault());

// First attempt generates a random desktop user agent
$userAgent = $session->forRequest($requestId)->value();

// Subsequent retries for the same request re-use the cached value
$retryUserAgent = $session->forRequest($requestId)->value();

Updating Browser Versions

vendor/bin/update-browser-versions

Fetches current releases from browsers.fyi and rewrites resources/browser_versions.json. This keeps version pools aligned with the latest stable browser releases.

Testing

composer test

Or run PHPUnit directly:

vendor/bin/phpunit tests

Contributing

1. Fork the repository and create your branch (git checkout -b feature/your-feature).
2. Run tests (composer test) and ensure coding standards pass (composer lint).
3. Submit a pull request.

License

Proprietary – contact JOOservices for licensing details.