README

简介

SimilarWeb 是由 SimilarGroup 公司创建的一个项目。它收集并提供了各种网站分析数据的访问权限。这是一个实现对它们的 API 容易访问的 PHP 库。

如果您想了解每个版本中发生了什么变化，请参阅此存储库根目录中的 CHANGELOG 文件。

要求

• PHP 5.3 (命名空间)，
• Symfony 的 YAML 库（解析映射数据）。

安装

此库可在 Packagist 上找到，并使用 thunderer/similarweb-api 别名。如果您使用 Composer（如果您不使用，我真的不知道你在等什么）您可以通过 composer require 安装它

composer require thunderer/similarweb-api

或者您可以将它手动放置在您的 composer.json 中

(...)
"require": {
    "thunderer/similarweb-api": "dev-master"
}
(...)

然后根据需要运行 composer install 或 composer update。

此库需要从其配置中生成的 Request 和 Response 类。如果您使用 Composer，请在 composer.json 文件中的 "scripts" 块中添加适当的条目，如下面的示例所示，以在安装或更新期间自动生成它们。在其他情况下，请从命令行手动运行 php bin/generate。您可以在内部部分了解更多关于此主题的信息。

包含易于使用的接口的实用类 ClientFacade 也在 Request 和 Response 类之后生成。

"scripts": {
    "post-install-cmd": "php vendor/thunderer/similarweb-api/bin/generate",
    "post-update-cmd": "php vendor/thunderer/similarweb-api/bin/generate"
}

当然，您可以将其作为 git 子模块、下载并放置在您的项目旁边，但请真的为自己（以及整个行业）做点好事，并使用 Composer。

用法

此库中实现的所有 API 都具有与 SimilarWeb API 文档中定义的相应的 Request 和 Response 类。应通过首先访问 SimilarWeb API 文档，然后使用位于 src/Request 目录中的具有相同名称的 Request 类来检索预期数据。以下所示的 getResponse() 方法将自动匹配、创建并返回匹配的 Response 类对象，该对象可以进行类型提示并依赖。还有一个包含易于使用的接口的 ClientFacade 类（请注意，此类是自动生成的）

use Thunder\SimilarWebApi\Client;
use Thunder\SimilarWebApi\ClientFacade;
use Thunder\SimilarWebApi\RawResponse;
use Thunder\SimilarWebApi\Request\Traffic as TrafficRequest;
use Thunder\SimilarWebApi\Response\Traffic as TrafficResponse;

// create client object
$client = new Client($yourUserKey, $desiredFormat);
$clientFacade = new ClientFacade($client);

// fetch response by passing API call name and desired domain
$response = $clientFacade->getTrafficResponse('kowalczyk.cc');
// or if you prefer to do it manually
$response = $client->getResponse(new TrafficRequest('kowalczyk.cc'));

// domain response class provides readable interface to get required information
/** @var $response TrafficResponse */
$rank = $response->getGlobalRank();

// there is also a raw response class which is used underneath
/** @var $rawResponse RawResponse */
$rawResponse = $response->getRawResponse();
$globalRank = $rawResponse->getValue('globalRank');

// check it by comparing both values:
assert($rank === $globalRank, 'Report an issue if you see this text.');

内部

此库的核心是一个名为 mapping.yaml 的文件，其中包含每个 API 返回的数据的定义。此库需要存在使用 bin/generate 脚本从该文件中存储的数据生成的 Request 和 Response 类。在本节中，将描述并引用 API GlobalRank 作为示例。这是其映射配置

GlobalRank:
  path: globalRank
  url: /Site/{domain}/{path}?Format={format}&UserKey={token}
  values:
    rank:
      json: { field: Rank }
      xml: { field: Rank }

它声明存在一个名为 GlobalRank 的 API，它使用 URL 部分 globalRank 并返回一个值，库将其称为 rank，从 JSON 键 Rank 或 XML 元素 Rank 读取。从这样的配置中，bin/generate 脚本将创建两个类：Thunder\SimilarWebApi\Request\GlobalRank 和 Thunder\SimilarWebApi\Response\GlobalRank，它们分别用作输入和输出对象，传递给和从 Thunder\SimilarWebApi\Client::getResponse() 方法返回。

API 返回包含四个类型数据的关联数组

• value：原始值，例如整数、字符串或日期（rank：2），
• array：一种类型的原始值数组（months：[1, 3, 5]）
• map：键值关联数组（域：[google.com: 3, google.pl: 7]），
• tuple：具有所选数据片段作为键和其余关联值作为值的关联数组。

在执行composer install、composer update或手动执行php bin/generate命令期间，API映射配置用于生成域请求和响应类，这些类使用方法隐藏库的复杂性，并通过可读的访问器提供可读的API。这种做法使得即使在没有额外编程工作的前提下，也能拥有可读的类API、良好的IDE自动完成和突出显示功能。当解析响应时，给定类型的所有元素都放在它们的容器中，这些响应类充当原始响应对象的门面。

$response = $client->getResponse(/* ... */);
$rawResponse = $response->getRawResponse();

$response->getRank() === $rawResponse->getValue('rank');

许可证

请参阅此存储库根目录中的LICENSE文件。