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

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

• value：基本值，如整数、字符串或日期（排名：2），
• array：一种类型的基本值的数组（月份：[1, 3, 5]），
• map：键值关联数组（域名：[google.com: 3, google.pl: 7]），
• tuple：具有所选数据作为键的关联数组，其余数据的关联值作为值。

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

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

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

许可证

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