browscap-php

Install the library using Composer to add it to your project dependencies.

composer require browscap/browscap-php 

Before using the library, you must download the browscap.ini file and convert it into a cache. There are two recommended workflows:

Option A: Two-step process (Manual control)

Download the file locally, then convert it. This is useful if you want to keep the .ini file locally. If the cache is corrupted, you only need to rerun convert.

vendor/bin/browscap-php browscap:fetch
vendor/bin/browscap-php browscap:convert

Option B: One-step process (Automatic update)

Download and convert in one command. This checks if the remote file has changed. If the cache is corrupted, you must clean the cache and restart the process.

vendor/bin/browscap-php browscap:update

Note: It is recommended to run these commands via a separate cron job to keep your cache updated.

If your environment requires a proxy to reach browscap.org, you can inject a custom Guzzle client into the BrowscapUpdater.

$proxyConfig = [
    'proxy' => [
        'http'  => 'tcp://localhost:8125',
        'https' => 'tcp://localhost:8124',
    ],
];
$client = new \GuzzleHttp\Client($proxyConfig);
$bcu = new BrowscapUpdater();
$bcu->setClient($client);

To identify a browser, instantiate \BrowscapPHP\Browscap. This class requires a PSR-16 compatible cache and a PSR-3 compatible logger. You can then call getBrowser() to identify the current user agent or pass a specific string to getBrowser($userAgent) to parse a custom string.

$cache = new \MatthiasMullie\Scrapbook\Psr16\SimpleCache($doctrineFileCache); // Must implement PSR-16
$logger = new \Monolog\Logger('name'); // Must implement PSR-3

$browscap = new \BrowscapPHP\Browscap($cache, $logger);

// Identify current user agent from $_SERVER
$info = $browscap->getBrowser();

// Identify a specific user agent
$info = $browscap->getBrowser($the_user_agent);

By default, the library uses the standard version of the browser capabilities file. To use the full version, use the BrowscapUpdater class and specify the PHP_INI_FULL constant.

$bc = new \BrowscapPHP\BrowscapUpdater();
$bc->update(\BrowscapPHP\Helper\IniLoaderInterface::PHP_INI_FULL);

The following commands are available via the bin/browscap.php entrypoint:

convert: Converts the browscap data.
update: Updates the browscap data.
parser: Runs the parser.
fetch: Fetches the browscap data.
check-update: Checks for updates.

The BrowscapPHP\Exception class defines several constant error codes used to identify specific failure scenarios during Browscap.ini parsing, file handling, or cache management. When catching exceptions from the library, you can check the exception code against these constants to handle different error types programmatically.

// Example of checking for a specific error code
try {
    // ... browscap operations ...
} catch (\BrowscapPHP\Exception $e) {
    if ($e->getCode() === \BrowscapPHP\Exception::INI_FILE_MISSING) {
        // Handle missing ini file
    }
}

The browscap:parse command allows you to analyze a specific user agent string and output the resulting browser capabilities in a pretty-printed JSON format.

Usage

Run the command followed by the user agent string you wish to analyze.

Arguments

• user-agent (Required): The user agent string to analyze.

Options

• --cache, -c (Optional): Specifies the directory where the cache files are located. If not provided, it uses the default cache folder configured for the application.

Exit Codes

• 0: Success
• 11: PARSER_ERROR (Occurs if parsing fails or JSON encoding fails)

php browscap:parse "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."

# Example with custom cache directory
php browscap:parse "Mozilla/5.0 ..." --cache /path/to/custom/cache