README

介绍

Crossjoin\Browscap允许根据用户代理字符串检查浏览器设置，使用浏览器功能项目的数据。

尽管PHP有原生的get_browser()函数来做这个，但这个实现提供了一些优点

• PHP函数需要设置browscap.ini文件的路径在php.ini指令中的browscap，它标记为PHP_INI_SYSTEM（因此只能在php.ini或httpd.conf中设置，这在许多情况下是不允许的，例如在共享主机环境中）。
• 它比PHP函数快得多（根据PHP版本、搜索的用户代理和其他因素，可达数百倍）
• 它允许自动更新Browscap源数据，因此您始终保持最新。

与其他PHP Browscap解析器相比，此实现具有以下优点

• 默认解析器非常快，因为它在内部SQLite数据库中的存储进行了优化。
• 它支持PHP版本5.6.x（版本2.x）到7.x（版本3.x），并使用最新可用的功能以获得最佳性能。
• 它的内存消耗非常低（用于解析和生成解析数据）。
• 所有组件都是可扩展的 - 使用您自己的源、解析器（写入器和读取器）或格式化程序。
• 使用属性过滤器从解析数据中移除不必要的Browscap属性和/或输出。
• 要么使用自动更新功能，要么通过命令行运行更新。

您还可以切换要使用的数据集类型

• standard数据集（浏览器属性的常规集合）
• lite数据集（浏览器属性的减少集合）
• full数据集（额外的浏览器属性）
• 提示：使用尽可能小的数据集以获得最佳性能，因为数据越详细，需要比较的用户代理就越多。

要求

• PHP 7.x（有关旧版本的支持，请参阅下文）
• 'pdo_sqlite'或'sqlite3'扩展（请注意，在composer安装/更新期间不检查此扩展，因为只需其中之一，而composer不支持此类要求）。
• 为了获得最佳性能，SQLite库版本应大于等于3.8.3（以使用递归查询）。
• 对于通过下载进行更新：cURL扩展，在php.ini中启用allow_url_fopen（有关更多详细信息，请参阅GuzzleHttp文档）

旧PHP版本发布

• 对于PHP 5.6.x版本，请使用Crossjoin\Browscap 2.x
• 对于旧版本的PHP，请参阅Crossjoin\Browscap 1.x

包安装

Crossjoin\Browscap以Composer包的形式提供，可以通过将包添加到您的composer.json文件中进行安装

{
    "require": {
        "crossjoin/browscap": "~3.0.0"
    }
}

基本用法

简单示例

通常您可以直接使用Browscap解析器。如果可能，缺失的数据将自动创建（尝试多个可用选项）。

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Get current browser details (taken from $_SERVER['HTTP_USER_AGENT'])
$settings = $browscap->getBrowser();
 
// or explicitly set the user agent to check
$settings = $browscap->getBrowser('user agent string');

自动更新

尽管缺失数据会自动创建，但默认情况下禁用了自动更新（与1.x版本不同）。要启用自动更新，您必须设置更新概率。

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Activate auto-updates
// Value: Percentage of getBrowser calls that will trigger the update check
$browscap->setAutoUpdateProbability(1);
 
// Get current browser details (taken from $_SERVER['HTTP_USER_AGENT'])
$settings = $browscap->getBrowser();

手动更新

可以使用脚本运行手动更新...

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
$forceUpdate = false; // If you do not force an update, it will only be done if required
 
// Run update
$browscap->update($forceUpdate);

或者通过命令行界面（您将在Composers的bin目录中找到'browscap'或'browscap.bat'，通常在'vendor/bin'）

browscap update [--force]

格式化程序

PHP get_browser()函数的替代品

默认情况下，返回的设置格式类似于PHP get_browser()函数的结果。因此，您将获得一个标准的PHP对象，具有特殊的属性/属性值格式。与get_browser()一样，您也可以通过修改格式化程序以获取数组作为返回值。

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Get standard object
$settings = $browscap->getBrowser();
 
// Get array
$arrayFormatter = new \Crossjoin\Browscap\Formatter\PhpGetBrowser(true);
$browscap->setFormatter($arrayFormatter);
$settings = $browscap->getBrowser();

或者，您可以将Browscap对象用作函数，与PHP get_browser()函数具有相同的参数，因此更容易作为替代品使用。

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Get standard object
$settings = $browscap('user agent string');
 
// Get array
$settings = $browscap('user agent string', true);

优化格式化程序

标准格式并不总是最优的，新的Optimized格式化程序通常是更好的选择。它不更改属性名称，返回所有具有正确类型的值（如果对所有可能的属性值都有效），并用NULL值替换'unknown'字符串。它还会从结果集中删除不再使用的属性（如'AolVersion'）。

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Get optimized result
$optimizedFormatter = new \Crossjoin\Browscap\Formatter\Optimized();
$browscap->setFormatter($optimizedFormatter);
$settings = $browscap->getBrowser();

自定义格式化程序

当然，您也可以创建自己的格式化程序，无论是通过使用通用格式化程序\Crossjoin\Browscap\Formatter\Formatter并设置所需选项（见下文），还是创建一个新的扩展\Crossjoin\Browscap\Formatter\FormatterInterface的格式化程序。

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Get customized result
$formatter = new \Crossjoin\Browscap\Formatter\Formatter(
    \Crossjoin\Browscap\Formatter\Formatter::RETURN_ARRAY |
    \Crossjoin\Browscap\Formatter\Formatter::KEY_LOWER |
    \Crossjoin\Browscap\Formatter\Formatter::VALUE_TYPED
);
$browscap->setFormatter($formatter);
$settings = $browscap->getBrowser();
 
// Use custom formatter tah extends \Crossjoin\Browscap\Formatter\FormatterInterface
$formatter = new \My\Formatter();
$browscap->setFormatter($formatter);
$settings = $browscap->getBrowser();

属性过滤器

如前所述，Optimized格式化程序从返回的数据中删除属性。这是通过过滤器完成的，这是2.x/3.x版本中的新功能。

过滤输出

您可以为格式化程序定义单个属性过滤器。

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Set list of allowed properties
$filter = new \Crossjoin\Browscap\PropertyFilter\Allowed();
$filter->setProperties(['Version', 'Browser', 'isMobileDevice']);
$browscap->getFormatter()->setPropertyFilter($filter);
 
// Only the allowed properties will be returned...
$settings = $browscap->getBrowser();
 
// Set list of disallowed properties
// IMPORTANT: The new property filter will replace the previous one!
$filter = new \Crossjoin\Browscap\PropertyFilter\Disallowed();
$filter->addProperty('Comment');
$filter->addProperty('browser_name_pattern');
$filter->addProperty('browser_name_regex');
 
// Properties except the filtered ones will be returned...
$settings = $browscap->getBrowser();
 
// Remove the filter by setting it to the default filter
$filter = new \Crossjoin\Browscap\PropertyFilter\None();
$browscap->getFormatter()->setPropertyFilter($filter);
 
// All properties will be returned...
$settings = $browscap->getBrowser();

过滤解析器数据

不仅输出可以被过滤。您还可以在创建数据集时过滤数据，这可以通过从源创建数据集来降低生成数据库的大小，最多可达50%。

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Set list of allowed properties
$filter = new \Crossjoin\Browscap\PropertyFilter\Allowed();
$filter->setProperties(['Version', 'Browser', 'isMobileDevice']);
$browscap->getParser()->setPropertyFilter($filter);
 
// Only the filtered properties are returned...
$settings = $browscap->getBrowser();
 
// Of course you can still define additional property filters for the formatter
// to further reduce the number of properties.
$filter = new \Crossjoin\Browscap\PropertyFilter\Disallowed(['isMobileDevice']);
$browscap->getFormatter()->setPropertyFilter($filter);
 
// Properties are now reduced to 'Version' and 'Browser'...
// NOTE: New parser property filters will trigger an update of the parser data!
$settings = $browscap->getBrowser();

您还可以在通过命令行界面使用解析器时设置过滤器。

browscap update --filter-allowed Version,Browser,isMobileDevice

browscap update --filter-disallowed Version,Browser,isMobileDevice

来源

默认情况下，当前browscap（PHP ini变体）来源将自动下载（standard类型）。

更改下载的源类型

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Set the 'standard' source (medium data set, with standard properties)
$type = \Crossjoin\Browscap\Type::STANDARD;
$source = new \Crossjoin\Browscap\Source\Ini\BrowscapOrg($type);
$browscap->getParser()->setSource($source);
 
// Set the 'lite' source (smallest data set, with the most important properties)
$type = \Crossjoin\Browscap\Type::LITE;
$source = new \Crossjoin\Browscap\Source\Ini\BrowscapOrg($type);
$browscap->getParser()->setSource($source);
 
// Set the 'full' source (largest data set, with additional properties)
$type = \Crossjoin\Browscap\Type::FULL;
$source = new \Crossjoin\Browscap\Source\Ini\BrowscapOrg($type);
$browscap->getParser()->setSource($source);
 
// Get properties...
// NOTE: New parser sources will trigger an update of the parser data!
$settings = $browscap->getBrowser();

您还可以在命令行界面设置源类型

browscap update --ini-load standard

browscap update --ini-load lite

browscap update --ini-load full

使用在 browscap PHP 指令中定义的源文件

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Use the browscap file defined in the PHP settings (e.g. in php.ini)
$source = new \Crossjoin\Browscap\Source\Ini\PhpSetting();
$browscap->getParser()->setSource($source);
 
// Get properties...
// NOTE: New parser sources will trigger an update of the parser data!
$settings = $browscap->getBrowser();

您也可以在命令行界面切换到这个源

browscap update --ini-php

使用自定义源文件

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Set a custom file as source
$source = new \Crossjoin\Browscap\Source\Ini\File('path/to/browscap.ini');
$browscap->getParser()->setSource($source);
 
// Get properties...
// NOTE: New parser sources will trigger an update of the parser data!
$settings = $browscap->getBrowser();

使用命令行界面设置源文件也是可能的

browscap update --ini-file path/to/browscap.ini

杂项设置

数据目录

解析器数据保存在系统的临时目录中，但您可以定义一个自己的目录

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Set a custom data directory
$parser = new \Crossjoin\Browscap\Parser\Sqlite\Parser('path/to/data/directory');
$browscap->setParser($parser);
 
// Get properties...
// NOTE: A new parser data directory will trigger an update of the parser data!
$settings = $browscap->getBrowser();

您也可以在命令行界面设置数据目录

browscap update --dir path/to/data/directory

源下载的客户端设置

如果您下载源，您可能想要为客户端使用代理或其他设置。您可以通过提供 GuzzleHttp 客户端（请参阅GuzzleHttp 文档）的设置来实现

<?php
// Include composer auto-loader
require_once '../vendor/autoload.php';
 
// Init
$browscap = new \Crossjoin\Browscap\Browscap();
 
// Set a custom data directory
$type = \Crossjoin\Browscap\Type::STANDARD;
$clientSettings = ['proxy' => 'tcp://127.0.0.1:8125'];
$source = new \Crossjoin\Browscap\Source\Ini\BrowscapOrg($type, $clientSettings);
$browscap->getParser()->setSource($source);
 
// Get properties...
$settings = $browscap->getBrowser();

请注意：目前使用命令行界面时无法实现此功能。

性能提示

始终使用最小的数据集

Browscap 数据有三种版本 - lite、standard 和 full - 浏览器的属性数量不同。当然，解析器数据库的大小也会随着源数据中包含的属性数量而增加 - 但这只会对性能产生微小影响，它只影响当数据库未被 PHP 缓存时的一些请求。

更重要的是，随着属性数量的增加，模式数量也会增加，因为检查需要变得更加详细以区分它们。这在解析时花费的时间最多，因为预过滤模式非常困难，并且经常有多个模式与给定的用户代理字符串匹配 - 因此在某些情况下，单个用户代理字符串会检查数千个模式。

因此，您应该始终使用可能的最小源类型，因为它包含的模式数量最少。此外，属性过滤器在这里也无济于事 - 它们有助于减少数据库的大小，但不会减少模式数量。例如，如果您使用 full 源类型并设置过滤器以仅获取 lite 源类型的属性，那么两种类型都会得到相同的结果，但 full 类型的耗时约为三倍。

问题和功能请求

请将您的问题和在 GitHub 问题跟踪器上请求新功能：[https://github.com/crossjoin/browscap/issues](https://github.com/crossjoin/browscap/issues)

请将 browscap.ini 文件中的错误识别的用户代理和浏览器检测报告给 Browscap：[https://github.com/browscap/browscap/issues](https://github.com/browscap/browscap/issues)