Merge branch 'main' of github.com:hexydec/agentzero into main

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
@@ -77,16 +77,53 @@ The returned value will be something like:
 	public readonly ?string 'proxy' => null;
 
 	// screen
-	public readonly ?int 'width' => int 1080
-	public readonly ?int 'height' => int 2116
-	public readonly ?int 'dpi' => int 420
+	public readonly ?int 'width' => int 1080;
+	public readonly ?int 'height' => int 2116;
+	public readonly ?int 'dpi' => int 420;
 	public readonly ?float 'density' => null;
 	public readonly ?bool 'darkmode' => null;;
 );
 ```
 
 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 (Warning: This will cause an extra round trip as the browser must re-request the first page).
+
+### 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).

composer.lock

@@ -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>

index.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/agentzero.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/config.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',