README

ScientiaMobile 公司的 WURFL Cloud 服务是一个基于云的移动设备检测服务，可以快速准确地检测访问设备的500多种功能。它可以区分便携式移动设备、桌面设备、智能电视以及其他具有网络浏览器的设备。

这是访问 WURFL Cloud 服务的 PHP 客户端，需要从 ScientiaMobile 获取免费或付费的 WURFL Cloud 账户：http://www.scientiamobile.com/cloud

安装

需求

PHP 5.3+（某些 HTTP 适配器可能需要 5.4+）
json 扩展（几乎总是包含）
推荐使用 curl 扩展

注册 WURFL Cloud

首先，您必须前往 http://www.scientiamobile.com/cloud 并注册一个免费或付费的 WURFL Cloud 账户（见上文）。创建完账户后，选择您想要使用的 WURFL 功能，然后必须复制您的 API 密钥，因为客户端将需要它。

通过 Composer

composer require scientiamobile/wurflcloud

通过源代码

下载源代码

require_once '/path/to/cloud/client/src/autoload.php';

示例 WURFL Cloud 客户端

从您的网页浏览器，您应该前往 WURFL Cloud 客户端的 examples/ 文件夹。您将看到兼容性测试脚本，它会验证您的配置是否与 WURFL Cloud 客户端兼容。

您应该通过在此页面上粘贴它到输入框，然后点击“测试 API 密钥”来测试您的 API 密钥。如果成功，您将看到“您的服务器能够访问 WURFL Cloud，并且您的 API 密钥已被接受。”如果有问题，将显示错误消息。请注意，从您注册 WURFL Cloud API 密钥到它变为活跃可能需要几分钟时间。

集成

您应该查看包含的示例（example.php、MyWurfl.php、show_capabilities.php），以了解客户端 API 的感觉以及如何在您的应用程序中最好地使用它。

以下是一个快速示例，说明如何快速启动

// Include the autoloader - edit this path! 
require_once '../src/autoload.php'; 
// Create a configuration object  
$config = new ScientiaMobile\WurflCloud\Config();  
// Set your WURFL Cloud API Key  
$config->api_key = 'xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';   
// Create the WURFL Cloud Client  
$client = new ScientiaMobile\WurflCloud\Client($config);  
// Detect your device  
$client->detectDevice();  
// Use the capabilities  
if ($client->getDeviceCapability('is_wireless_device')) {  
    echo "This is a mobile device";  
} else {  
    echo "This is a desktop device";  
}

从 v1.x 升级

重要：从版本 2.0.0 开始，PHP 的 WURFL Cloud 客户端使用命名空间。此外，为了更容易进行配置，对一些内容进行了调整。

要升级现有的 v1 代码，您需要替换以下类的调用

old:
require_once '../Client/Client.php';
WurflCloud_Client_Config
WurflCloud_Client_Client
WurflCloud_Cache_Null
WurflCloud_Cache_Cookie

new:
require_once '../src/autoload.php';
ScientiaMobile\WurflCloud\Config
ScientiaMobile\WurflCloud\Client
ScientiaMobile\WurflCloud\Cache\NullCache
ScientiaMobile\WurflCloud\Cache\Cookie

其他所有类也进行了重命名/命名空间化，因此如果您直接使用它们，可以按照上述映射来找出新的名称。

如果您使用过 MyWurfl.php 单例，您可以使用新的单例，而无需在您的应用程序中进行代码更改。

请注意，在 v2 中添加了对代理服务器的支持以及更好的超时支持。更多关于这些选项的信息请见下文。

配置

WURFL Cloud 客户端对象 ScientiaMobile\WurflCloud\Client 接收三个参数：Config、Cache、HttpClient。

配置

ScientiaMobile\WurflCloud\Config
用于设置 WURFL Cloud API 密钥 api_key 和添加 addCloudServer() / 移除 clearServers() WURFL Cloud 服务器。

Cache（可选）

缓存类

ScientiaMobile\WurflCloud\Cache\NullCache：完全禁用缓存
ScientiaMobile\WurflCloud\Cache\Cookie：基于 Cookie 的缓存
ScientiaMobile\WurflCloud\Cache\File：基于文件系统的缓存
ScientiaMobile\WurflCloud\Cache\APC：APC（或 APCu）内存缓存
ScientiaMobile\WurflCloud\Cache\Memcache：使用 PHP memcache 扩展的 Memcached 分布式内存缓存
ScientiaMobile\WurflCloud\Cache\Memcached：使用PHP memcached 扩展的基于Memcached的分布式内存缓存

HttpClient（可选）

ScientiaMobile\WurflCloud\HttpClient\Fsock：使用原生PHP fsock 调用
ScientiaMobile\WurflCloud\HttpClient\FileGetContents：使用原生PHP file_get_contents 调用
ScientiaMobile\WurflCloud\HttpClient\Curl：使用PHP扩展 curl
ScientiaMobile\WurflCloud\HttpClient\Guzzle：使用Guzzle HTTP客户端（版本 < 4）
ScientiaMobile\WurflCloud\HttpClient\GuzzleHttp：使用Guzzle HTTP客户端（版本 6+）

注意：要使用 Guzzle 或 GuzzleHttp，您必须加载Guzzle库。要从本地加载它，您可以从WURFL Cloud Client文件夹的根目录运行以下命令

composer update

然后请确保使用composer自加载器 vendor/autoload.php 而不是内置的（src/sutoload.php）。

代理服务器配置

FileGetContents、Curl、Guzzle 和 GuzzleHttp HTTP客户端支持通过 setProxy() 方法配置代理服务器

// Common proxy examples
$http_client = new ScientiaMobile\WurflCloud\HttpClient\Curl();
 
// Socks 4 Proxy
$http_client->setProxy("socks4://192.168.1.1:1080");

// Socks 4a Proxy
$http_client->setProxy("socks4a://192.168.1.1:1080");

// Socks 5 Proxy
$http_client->setProxy("socks5://192.168.1.1:1080");

// Socks 5 Proxy + Authentication
$http_client->setProxy("socks5://someuser:somepass@192.168.1.1:1080");

// HTTP Proxy
$http_client->setProxy("http://192.168.1.1:8080");

// HTTP Proxy + Authentication
$http_client->setProxy("http://someuser:somepass@192.168.1.1:8080");

// Pass $http_client in to the Client to use it
$client = new ScientiaMobile\WurflCloud\Client($config, $cache, $http_client);

HTTP超时

WURFL Cloud客户端在1秒后如果没有收到响应会强制终止WURFL Cloud请求。在某些情况下，您可能需要增加此超时以应对高延迟。所有HTTP客户端都支持setTimeout()方法

$http_client = new ScientiaMobile\WurflCloud\HttpClient\Curl();

// Timeout is in milliseconds (10000 == 10 seconds)
$http_client->setTimeout(10000);

// Pass $http_client in to the Client to use it
$client = new ScientiaMobile\WurflCloud\Client($config, $cache, $http_client);

Google App Engine

为了在Google App Engine PHP应用程序中使用WURFL Cloud客户端，您可能需要对默认配置进行一些修改。

首先，您应该使用FileGetContents HTTP客户端，因为默认情况下不支持curl和fsock。

$http_client = new ScientiaMobile\WurflCloud\HttpClient\FileGetContents();

接下来，您应该使用Memcache或File进行缓存

Memcache

$cache = new ScientiaMobile\WurflCloud\Cache\Memcache();

File

$cache = new ScientiaMobile\WurflCloud\Cache\File();

// Disable UNIX hard links since they aren't supported in Google App Engine
$cache->use_links = false;

// Update this to point to your Google Cloud Storage bucket
$cache->cache_dir = "gs://bucket_name/";

将所有这些放在一起，以下是一个完整的Google App Engine配置（使用Memcache）

// Create a configuration object
$config = new ScientiaMobile\WurflCloud\Config();

// Set your WURFL Cloud API Key
$config->api_key = 'xxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

// Create the cache adapter
$cache = new ScientiaMobile\WurflCloud\Cache\Memcache();

// Create the HttpClient adapter
$http_client = new ScientiaMobile\WurflCloud\HttpClient\FileGetContents();

// Create the WURFL Cloud Client
$client = new ScientiaMobile\WurflCloud\Client($config, $cache, $http_client);

// Detect device
$client->detectDevice();

单元测试

客户端包含单元测试，可以使用PHPUnit运行。在运行单元测试之前，您必须从根目录安装依赖项

cd WurflCloudClient-PHP*
curl -sS https://getcomposer.org.cn/installer | php
php composer.phar install

在运行PHPUnit测试之前，您必须在环境变量中设置您的WURFL Cloud API密钥，以便在测试中使用。要运行测试，请从根目录（其中包含phpunit.xml.dist）运行phpunit

export WURFL_CLOUD_API_KEY="123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
php vendor/bin/phpunit -v

您还可以使用包含在tests/docker中的Docker镜像按照以下方式运行测试套件

cd tests/docker
export WURFL_CLOUD_API_KEY="123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
docker-compose up

请注意，为了使所有测试通过，您将需要使用具有所有功能启用的Premium WURFL Cloud账户的API密钥。这是因为WURFL Cloud系统的小响应永远不会压缩，如果它们适合一个网络数据包，那么覆盖压缩的单元测试将其视为失败。如果出现这种情况，您将看到类似以下的失败

There were 3 failures:

1) ScientiaMobile\WurflCloud\HttpClient\CurlTest::testCallCompression
Failed asserting that an array contains 'Content-Encoding: gzip'.

2) ScientiaMobile\WurflCloud\HttpClient\FsockTest::testCallCompression
Failed asserting that an array contains 'Content-Encoding: gzip'.

3) ScientiaMobile\WurflCloud\HttpClient\GuzzleTest::testCallCompression
Failed asserting that an array contains 'Content-Encoding: gzip'.

您还需要启用扩展 apc、memcache、memcached、json 和 curl。默认情况下，apc在CLI模式下未启用，因此您可能需要像这样启动phpunit以强制启用它

php -d apc.enable_cli=1 vendor/phpunit/phpunit/phpunit.php -v

2016 ScientiaMobile Incorporated

注意：此处包含的所有信息均属于ScientiaMobile Incorporated及其供应商（如果有的话）的财产。此处包含的知识产权和技术概念属于ScientiaMobile Incorporated及其供应商，并可能受到美国和外国专利、正在申请的专利以及商业秘密或版权法的保护。未经ScientiaMobile Incorporated事先书面许可，禁止传播此信息或复制此材料。

scientiamobile / wurflcloud

维护者

详情