Fixed bug versions::load() where if the cache folder already existed by the cache file didn't, the cache file wasn't written.

Changed default setting to not specify where the versions cache file is stored, thus version information will not be retrieved unless it is explicitly set.
Updated `versions::get()` to handle when the cache file has not been specified.
Fixed issue in `versions::get()` where the `currentdate` parameter was not passed to `versions::latest()`.
Flattened version settings so they are not in their own sub array.
Added `agentzero::getHints()` to retrieve the client hints sent by the browser.
Updated `README.md` with information on how to parse client hints and add versioning information.

Author: hexydec

README.md

@@ -60,8 +60,8 @@ The returned value will be something like:
 	public readonly ?string 'browser' => string 'Chrome';
 	public readonly ?string 'browserversion' => string '116.0.0.0';
 	public readonly ?string 'browserstatus' => 'previous';
-    public readonly ?string 'browserreleased' => '2023-09-15';
-    public readonly ?string 'browserlatest' => '133.0.6943.54';
+	public readonly ?string 'browserreleased' => '2023-09-15';
+	public readonly ?string 'browserlatest' => '133.0.6943.54';
 	public readonly ?string 'language' => string 'en-GB';
 
 	// app
@@ -87,6 +87,43 @@ The returned value will be something like:
 
 You can read the [full list of properties here](docs/api.md).
 
+### Client Hints
+
+AgentZero now supports processing client hints for improved user-agent information. You must request the client hints to improve the information delivered through the user-agent string:
+
+```php
+
+// request client hints
+\header('Accept-CH: Width, ECT, Device-Memory, Sec-CH-UA-Platform-Version, Sec-CH-UA-Model, Sec-CH-UA-Full-Version-List');
+
+// retrieve client hints
+$hints = \hexydec\agentzero\agentzero::getHints();
+
+// parse
+$az = \hexydec\agentzero\agentzero::parse($_SERVER['HTTP_USER_AGENT'], $hints);
+```
+
+Note that by using the `Accept-CH` header, you may receive client hints on subsequent requests, if you need the client hints on first call, use the `Critical-CH` header instead.
+
+### Browser Versions
+
+You can determine the date the browser was released, latest version, and status, by setting where the version file should be cached:
+
+```php
+$config = [
+	'versionscache' => __DIR__.'/cache/versions.json'
+];
+$az = \hexydec\agentzero\agentzero::parse($_SERVER['HTTP_USER_AGENT'], [], $config);
+var_dump(
+	$ua->browserstatus, // either "canary", "beta", "latest", "previous", "legacy", legacy means released over 5 years ago
+	$ua->browserreleased, // the date the browser was released
+	$us->browserlatest // the latest version number of the browser
+);
+
+```
+
+The browser version information is sourced from [my browser versions project](https://github.com/hexydec/versions).
+
 ## Supported Features
 
 AgentZero supports a wide range of architectures, browsers, rendering engines, platforms, devices, languages, and crawlers. [Access the full list on the Supported Features page](docs/support.md).

index.php

@@ -1,20 +1,29 @@
 <?php
+
+use hexydec\agentzero\agentzero;
+
 require(__DIR__.'/src/autoload.php');
 
 // fetch UA string
 $ua = $_POST['ua'] ?? $_SERVER['HTTP_USER_AGENT'] ?? '';
 
 // client hints
-$hints = [
-	'sec-ch-ua-mobile' => $_POST['mobile'] ?? $_SERVER['HTTP_SEC_CH_UA_MOBILE'] ?? '',
-	'sec-ch-ua-full-version-list' => $_POST['browser'] ?? $_SERVER['HTTP_SEC_CH_UA_FULL_VERSION_LIST'] ?? '',
-	'sec-ch-ua-platform' => $_POST['platform'] ?? $_SERVER['HTTP_SEC_CH_UA_PLATFORM'] ?? '',
-	'sec-ch-ua-platform-version' => $_POST['platformversion'] ?? $_SERVER['HTTP_SEC_CH_UA_PLATFORM_VERSION'] ?? '',
-	'sec-ch-ua-model' => $_POST['model'] ?? $_SERVER['HTTP_SEC_CH_UA_MODEL'] ?? '',
-	'device-memory' => $_POST['memory'] ?? $_SERVER['HTTP_DEVICE_MEMORY'] ?? '',
-	'width' => $_POST['width'] ?? $_SERVER['HTTP_WIDTH'] ?? '',
-	'ect' => $_POST['ect'] ?? $_SERVER['HTTP_ECT'] ?? ''
+$hints = agentzero::getHints();
+$keys = [
+	'sec-ch-ua-mobile',
+	'sec-ch-ua-full-version-list',
+	'sec-ch-ua-platform',
+	'sec-ch-ua-platform-version',
+	'sec-ch-ua-model',
+	'device-memory',
+	'width',
+	'ect'
 ];
+foreach ($keys AS $item) {
+	if (!empty($_POST[$item])) {
+		$hints[$item] = $_POST[$item];
+	}
+}
 $memsizes = [
 	'0.25' => '256Mb',
 	'0.5' => '512Mb',
@@ -39,7 +48,7 @@
 
 // timing variables
 $time = \microtime(true);
-$output = \hexydec\agentzero\agentzero::parse($ua, \array_filter($hints));
+$output = \hexydec\agentzero\agentzero::parse($ua, \array_filter($hints), ['versionscache' => __DIR__.'/cache/versions.json']);
 $total = \microtime(true) - $time;
 ?>
 <!DOCTYPE html>
@@ -104,48 +113,48 @@
 				<h3>Client Hints</h3>
 				<div class="form__control">
 					<label class="form__label">Mobile:</label>
-					<select name="mobile">
+					<select name="sec-ch-ua-mobile">
 						<option value="">-- Select Mobile --</option>
 						<?php foreach ($devices AS $key => $item) { ?>
-							<option value="<?= \htmlspecialchars($key); ?>"<?= $hints['sec-ch-ua-mobile'] === $key ? ' selected="selected"' : ''; ?>><?= \htmlspecialchars($item); ?></option>
+							<option value="<?= \htmlspecialchars($key); ?>"<?= ($hints['sec-ch-ua-mobile'] ?? null) === $key ? ' selected="selected"' : ''; ?>><?= \htmlspecialchars($item); ?></option>
 						<?php } ?>
 					</select>
 				</div>
 				<div class="form__control">
 					<label class="form__label">Browser:</label>
-					<input type="text" class="form__input" name="browser" value="<?= \htmlspecialchars($hints['sec-ch-ua-full-version-list']); ?>" />	
+					<input type="text" class="form__input" name="sec-ch-ua-full-version-list" value="<?= \htmlspecialchars($hints['sec-ch-ua-full-version-list'] ?? ''); ?>" />	
 				</div>
 				<div class="form__control">
 					<label class="form__label">Platform:</label>
-					<input type="text" class="form__input--short" name="platform" value="<?= \htmlspecialchars($hints['sec-ch-ua-platform']); ?>" />	
+					<input type="text" class="form__input--short" name="sec-ch-ua-platform" value="<?= \htmlspecialchars($hints['sec-ch-ua-platform'] ?? ''); ?>" />	
 				</div>
 				<div class="form__control">
 					<label class="form__label">Platform Version:</label>
-					<input type="text" class="form__input--short" name="platformversion" value="<?= \htmlspecialchars($hints['sec-ch-ua-platform-version']); ?>" />
+					<input type="text" class="form__input--short" name="sec-ch-ua-platform-version" value="<?= \htmlspecialchars($hints['sec-ch-ua-platform-version'] ?? ''); ?>" />
 				</div>
 				<div class="form__control">
 					<label class="form__label">Model:</label>
-					<input type="text" class="form__input--short" name="model" value="<?= \htmlspecialchars($hints['sec-ch-ua-model']); ?>" />
+					<input type="text" class="form__input--short" name="sec-ch-ua-model" value="<?= \htmlspecialchars($hints['sec-ch-ua-model'] ?? ''); ?>" />
 				</div>
 				<div class="form__control">
 					<label class="form__label">Memory:</label>
-					<select name="memory">
+					<select name="device-memory">
 						<option value="">-- Select Memory --</option>
 						<?php foreach ($memsizes AS $key => $item) { ?>
-							<option value="<?= \htmlspecialchars($key); ?>"<?= $hints['device-memory'] == $key ? ' selected="selected"' : ''; ?>><?= \htmlspecialchars($item); ?></option>
+							<option value="<?= \htmlspecialchars($key); ?>"<?= ($hints['device-memory'] ?? null) == $key ? ' selected="selected"' : ''; ?>><?= \htmlspecialchars($item); ?></option>
 						<?php } ?>
 					</select>
 				</div>
 				<div class="form__control">
 					<label class="form__label">Width:</label>
-					<input type="number" class="form__input--short" name="width" value="<?= \htmlspecialchars($hints['width']); ?>" />
+					<input type="number" class="form__input--short" name="width" value="<?= \htmlspecialchars($hints['width'] ?? ''); ?>" />
 				</div>
 				<div class="form__control">
 					<label class="form__label">Connection:</label>
 					<select name="ect">
 						<option value="">-- Select Connection --</option>
 						<?php foreach ($conns AS $key => $item) { ?>
-							<option value="<?= \htmlspecialchars($key); ?>"<?= $hints['ect'] === $key ? ' selected="selected"' : ''; ?>><?= \htmlspecialchars($item); ?></option>
+							<option value="<?= \htmlspecialchars($key); ?>"<?= ($hints['ect'] ?? null) === $key ? ' selected="selected"' : ''; ?>><?= \htmlspecialchars($item); ?></option>
 						<?php } ?>
 					</select>
 				</div>

src/agentzero.php

@@ -145,6 +145,32 @@ public function __get(string $key) : string|int|null {
 		return $this->{$key} ?? null;
 	}
 
+	/**
+	 * Fetch the client hints sent by the browser
+	 * 
+	 * @return array<string,string> An array containing relevant client hints sent by the client
+	 */
+	public static function getHints() : array {
+		$hints = [
+			'sec-ch-ua-mobile',
+			'sec-ch-ua-full-version-list',
+			'sec-ch-ua-platform',
+			'sec-ch-ua-platform-version',
+			'sec-ch-ua-model',
+			'device-memory',
+			'width',
+			'ect'
+		];
+		$data = [];
+		foreach ($hints AS $item) {
+			$upper = \strtoupper(\str_replace('-', '_', $item));
+			if (!empty($_SERVER['HTTP_'.$upper])) {
+				$data[$item] = $_SERVER['HTTP_'.$upper];
+			}
+		}
+		return $data;
+	}
+
 	/**
 	 * Extracts tokens from a UA string
 	 * 

src/config.php

@@ -30,12 +30,10 @@ public static function get(array $config = []) : ?array {
 					apps::get(),
 					frameworks::get()
 				),
-				'versions' => [
-					'source' => 'https://raw.githubusercontent.com/hexydec/versions/refs/heads/main/dist/versions.json', // browser version data source
-					'cache' => \dirname(__DIR__).'/cache/versions.json', // location of the cache file
-					'cachelife' => 604800, // how long to cache for
-					'currentdate' => null // the point in time to calculate the browser data from, may be in the past (DateTime object)
-				]
+				'versionssource' => 'https://raw.githubusercontent.com/hexydec/versions/refs/heads/main/dist/versions.json', // browser version data source
+				'versionscache' => null, // location of the cache file, null to not fetch version data
+				'versionscachelife' => 604800, // how long to cache for
+				'currentdate' => null // the point in time to calculate the browser data from, may be in the past (DateTime object)
 			];
 		}
 		return \array_replace_recursive($default, $config);

src/helpers/hints.php

@@ -4,13 +4,20 @@
 
 class hints {
 
+	/**
+	 * Parses client hints to set agentzero properties
+	 * 
+	 * @param string &$ua A reference to the User-Agent string, which may be used with brand names and versions
+	 * @param array $hints An array of client hints
+	 * @return stdClass A stdClass object containing parsed values for agentzero
+	 */
 	public static function parse(string &$ua, array $hints) : \stdClass {
 		$map = [
 			'sec-ch-ua-mobile' => fn (\stdClass $obj, string $value) : string => $obj->category = $value === '?1' ? 'mobile' : 'desktop',
 			'sec-ch-ua-platform' => fn (\stdClass $obj, string $value) : ?string => $obj->platform = \trim($value, '"') ?: null,
 			'sec-ch-ua-platform-version' => function (\stdClass $obj, string $value) : void {
 				$value = \trim($value, '"');
-				if ($obj->platform === 'Windows') {
+				if (($obj->platform ?? null) === 'Windows') {
 					$map = [
 						'8',
 						'10.1507',

src/helpers/versions.php

@@ -4,9 +4,20 @@
 
 class versions {
 
+	/**
+	 * @var array|false|null An array of browser version numbers
+	 */
 	protected static array|false|null $versions = null;
 
-	protected static function load(string $source, ?string $cache = null, ?int $life = 604800) : array|false {
+	/**
+	 * Loads browser version information from an external source
+	 * 
+	 * @param string $source The URL of the source JSON containing the version information
+	 * @param string $cache The absolute file address of the cache file
+	 * @param ?int $life The maximum life of the cache file in seconds
+	 * @return array<string,array<string,string>> An array of browser versioning information, or false if the data source not be retrieved
+	 */
+	protected static function load(string $source, string $cache, ?int $life = 604800) : array|false {
 
 		// cache for this session
 		$data = self::$versions;
@@ -25,13 +36,11 @@ protected static function load(string $source, ?string $cache = null, ?int $life
 				}
 
 			// update cache
-			} elseif ($cache !== null) {
+			} else {
 
-				// create directory
+				// create directory and cache file
 				$dir = \dirname($cache);
-				if (!\is_dir($dir) && \mkdir($dir, 0755)) {
-
-					// cache file
+				if (\is_dir($dir) || \mkdir($dir, 0755)) {
 					\file_put_contents($cache, $json);
 				}
 			}
@@ -42,6 +51,11 @@ protected static function load(string $source, ?string $cache = null, ?int $life
 		return $data ?? false;
 	}
 
+	/**
+	 * Determines the latest version of a browser, optionally capped by the supplied date
+	 * 
+	 * @param array<string,string> $versions An array of browser versions, where the key is the version number and the value is the release date (In Ymd format)
+	 */
 	protected static function latest(array $versions, ?\DateTime $now = null) : ?string {
 
 		// no date restriction
@@ -86,12 +100,15 @@ protected static function released(array $data, string $version) : ?string {
 	}
 
 	public static function get(string $browser, string $version, array $config) : array {
-		if (($versions = self::load($config['source'], $config['cache'])) !== false) {
+		$source = $config['versionssource'];
+		$cache = $config['versionscache'];
+		$life = $config['versionscachelife'];
+		if ($cache !== null && ($versions = self::load($source, $cache, $life)) !== false) {
 			$data = [];
 			if (isset($versions[$browser])) {
 
 				// get latest version of the browser
-				$data['browserlatest'] = self::latest($versions[$browser]);
+				$data['browserlatest'] = self::latest($versions[$browser], $config['currentdate']);
 
 				// check if version is greater than latest version
 				$major = \intval($version);

src/mappings/browsers.php

@@ -56,7 +56,7 @@ protected static function getBrowser(string $value, int $i, array $tokens, strin
 		$key = $map[$data['browser']] ?? \mb_strtolower($data['browser']);
 		return \array_merge(
 			$data,
-			isset($data['browserversion']) ? versions::get($key, $data['browserversion'], $config['versions']) : []
+			isset($data['browserversion']) ? versions::get($key, $data['browserversion'], $config) : []
 		);
 	}
 	/**
@@ -103,7 +103,7 @@ public static function get() : array {
 					'browserversion' => $version ?? null,
 					'engine' => 'WebKit',
 					'engineversion' => $parts[1] ?? null
-				], $version !== null ? versions::get('safari', $version, $config['versions']) : []);
+				], $version !== null ? versions::get('safari', $version, $config) : []);
 			},
 		];
 		return [
@@ -118,7 +118,7 @@ public static function get() : array {
 			'Maxthon ' => new props('start', fn (string $value, int $i, array $tokens, string $key, array $config = []) : array => \array_merge([
 				'browser' => 'Maxthon',
 				'browserversion' => \mb_substr($value, 8)
-			], versions::get('maxathon', \mb_substr($value, 8), $config['versions']))),
+			], versions::get('maxathon', \mb_substr($value, 8), $config))),
 			'Konqueror/' => new props('start', $fn['browserslash']),
 			'K-Meleon/' => new props('start', $fn['browserslash']),
 			'UCBrowser/' => new props('start', $fn['browserslash']),
@@ -170,7 +170,7 @@ public static function get() : array {
 					'browser' => 'Midori',
 					'engine' => $major >= 11 ? 'Gecko' : ($major < 9 ? 'WebKit' : 'Blink'),
 					'browserversion' => $version
-				], $version !== null ? versions::get('midori', $version, $config['versions']) : []);
+				], $version !== null ? versions::get('midori', $version, $config) : []);
 			}),
 			'PrivacyBrowser/' => new props('start', $fn['browserslash']),
 			'Fennec/' => new props('start', $fn['gecko']),
@@ -220,19 +220,19 @@ public static function get() : array {
 				'browser' => 'Internet Explorer',
 				'browserversion' => \mb_substr($value, 5),
 				'engine' => 'Trident'
-			], versions::get('ie', \mb_substr($value, 5), $config['versions']))),
+			], versions::get('ie', \mb_substr($value, 5), $config))),
 			'BOIE9' => new props('start', fn (string $value, int $i, array $tokens, string $key, array $config = []) => \array_merge([
 				'type' => 'human',
 				'browser' => 'Internet Explorer',
 				'browserversion' => '9.0',
 				'engine' => 'Trident'
-			], versions::get('ie', '9.0', $config['versions']))),
+			], versions::get('ie', '9.0', $config))),
 			'IEMobile/' => new props('start', fn (string $value, int $i, array $tokens, string $key, array $config = []) : array => \array_merge([
 				'type' => 'human',
 				'browser' => 'Internet Explorer',
 				'browserversion' => \mb_substr($value, 9),
 				'engine' => 'Trident'
-			], versions::get('ie', \mb_substr($value, 9), $config['versions']))),
+			], versions::get('ie', \mb_substr($value, 9), $config))),
 			'Trident' => new props('start', [ // infill for missing browser name
 				'browser' => 'Internet Explorer'
 			]),

tests/lib.php

@@ -5,8 +5,11 @@
 class lib {
 
 	public static function parse(string $ua, array $hints = []) : array {
+		$config = [
+			'versionscache' => \dirname(__DIR__).'/cache/versions.json'
+		];
 		$arr = \array_filter(
-			\array_diff_key((array) agentzero::parse($ua, $hints), ['browserstatus' => '', 'browserlatest' => '']),
+			\array_diff_key((array) agentzero::parse($ua, $hints, $config), ['browserstatus' => '', 'browserlatest' => '']),
 			fn (mixed $item) : mixed => $item !== null
 		);
 		return $arr;