README

简介

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

尽管PHP有本地的get_browser()函数来执行此操作，但此实现提供了一些优势

• PHP函数需要在php.ini指令中的browscap中设置browscap.ini文件的路径，该指令标记为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格式化器通常是更好的选择。它不会更改属性名称，返回所有正确类型的值（如果对所有可能的属性值都有效），并将'unknown'字符串替换为NULL值。它还会从结果集中删除不再使用的属性（如'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 类型的处理时间将是 lite 类型的三倍左右。

问题和功能请求

请在 GitHub Issue Tracker 上报告您的问题并请求新功能：[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)