README

Diffbot PHP API 封装器

本包是一个略微过度设计的 Diffbot API 封装器。它使用 PSR-7 和 PHP-HTTP 的友好客户端实现来执行 API 调用。要了解更多关于 Diffbot 的信息，请访问这里和他们的主页。目前它只支持 Analyze、Product、Image、Discussion、Crawl、Search 和 Article API，但也可以支持自定义 API。视频和批量 API 支持即将推出。

完整文档可在这里获取。

要求

需要 PHP 5.6 或更高版本。建议使用 PHP 7.0。

本包使用了一些不稳定的包，因此您必须在 composer.json 中将项目的基本稳定性设置为类似 beta 或 dev。

"minimum-stability": "dev",
"prefer-stable": true

如果不这样做，下面的安装过程将失败。

安装

库依赖于 client-implementation 虚拟包的实现。如果您不知道这意味着什么，只需要求 Guzzle6 适配器即可

composer require php-http/guzzle6-adapter

此适配器满足客户端实现的要求（见上文），并可以使用以下方法安装客户端

composer require swader/diffbot-php-client

使用 - 简单

最简单的使用场景

$diffbot = new Diffbot('my_token');
$url = 'http://www.sitepoint.com/diffbot-crawling-visual-machine-learning/';
$articleApi = $diffbot->createArticleAPI($url);

echo $articleApi->call()->author; // prints out "Bruno Skvorc"

这就是全部，这是您开始所需的所有内容。

使用 - 高级

完整的 API 参考手册正在制作中，但以下说明应该足够了——该库的设计考虑了极端的用户界面简洁性。

设置

首先，始终创建一个 Diffbot 实例。Diffbot 实例将生成 API 实例。要获取您的令牌，请在 http://diffbot.com 注册

$diffbot = new Diffbot('my_token');

选择 API

然后，选择一个 API。

目前可用的 automatic API 有：

product（爬取产品和它们的评论，如果有的话）
article（爬取新闻帖子、博客等，如果有评论的话）
image（获取有关图像的信息 - 对于 500px、Flickr 等非常有用）。Image API 可以返回多个图像 - 具体取决于正在爬取的页面上有多少图像。
discussion（获取讨论/评论/评论线程 - 如果 Product 或 Article 返回数据中包含任何评论或讨论，也可以嵌入其中）
analyze（结合上述所有功能，因为它会自动确定适合 URL 的正确 API 并应用它）

视频即将推出。有关 Crawlbot、Search 和批量 API 的说明请见下文。

还有一个类似于 Custom API 的这个 - 除非另行配置，否则它们将返回 Wildcard 实体的实例。

所有API都可以在http://diffbot.com上进行测试

您选择的API可以通过主Diffbot实例启动

$api = $diffbot->createArticleAPI($url);

API配置

所有API都有一些可选字段，您可以将这些字段作为参数传递。例如，为了提取页面的'meta'值和常规数据，请调用setMeta

$api->setMeta(true);

一些API有其他标志，它们不算是字段。例如，文章API可以设置为忽略讨论（即不提取评论）。这可以加快获取速度，因为默认情况下，它会查找它们。尽管如此，配置方法都有相同的格式，因此要实现这一点，只需使用setDiscussion

$api->setDiscussion(false);

所有配置方法都是可链的

$api->setMeta(true)->setDiscussion(false);

有关所有配置字段和每个API返回的值的概述，请参见此处。

调用

所有API实例都有一个call方法，该方法返回一组结果。该集合是可迭代的

$url = 'http://smittenkitchen.com/blog/2012/01/buckwheat-baby-with-salted-caramel-syrup/';
$imageApi = $diffbot->createImageAPI($url);
/** @var Image $imageEntity */
foreach ($imageApi->call() as $imageEntity) {
    echo 'Image dimensions: ' . $imageEntity->getHeight() . ' x ' . $imageEntity->getWidth() . '<br>';
}

/* Output:
Image dimensions: 333 x 500
Image dimensions: 333 x 500
Image dimensions: 334 x 500
Image dimensions: 333 x 500
Image dimensions: 333 x 500
Image dimensions: 333 x 500
Image dimensions: 333 x 500
Image dimensions: 333 x 500
Image dimensions: 333 x 500
*/

在只返回一个实体的情况下，例如文章或产品，迭代操作与之前相同，它只是遍历一个单个元素。返回的数据始终是一个集合！

然而，为了简洁，您也可以直接访问集合上的属性。

$articleApi = $diffbot->createArticleAPI('http://www.sitepoint.com/diffbot-crawling-visual-machine-learning/');
echo $articleApi->call()->author;
// or $articleApi->call()->getAuthor();

在这种情况下，集合将属性调用应用于第一个元素，碰巧这也是唯一的元素。如果您在上面的图像集合上使用此方法，也会发生相同的事情 - 但调用只应用于集合中的第一个图像实体。

仅请求URL

如果您只想获取最终生成的URL（例如，将其粘贴到Postman客户端或用于在浏览器中进行测试以获取纯JSON），请使用buildUrl

$url = $articleApi->buildUrl();

之后您可以继续常规的API使用，这使得它在记录等操作中非常有用。

纯响应

您可以从返回的数据中提取纯的、完整的Guzzle响应对象，然后按需对其进行操作（可能将其解析为JSON并进一步处理）

$articleApi = $diffbot->createArticleAPI('http://www.sitepoint.com/diffbot-crawling-visual-machine-learning/');
$guzzleResponse = $articleApi->call()->getResponse();

单个实体无法访问响应 - 要获取它，始终从其父集合（即call()方法返回的对象）中获取。

讨论和帖子

讨论API返回有关讨论的一些数据，并包含另一个帖子集合。帖子实体对应单个评论/评论/论坛帖子，其结构与文章实体非常相似。

您可以像往常一样遍历帖子

$url = 'http://community.sitepoint.com/t/php7-resource-recap/174325/';
$discussion = $diffbot->createDiscussionAPI($url)->call();
/** @var Post $post */
foreach($discussion->getPosts() as $post) {
    echo 'Author: '.$post->getAuthor().'<br>';
}

/*
Output:

Author: swader
Author: TaylorRen
Author: s_molinari
Author: s_molinari
Author: swader
Author: s_molinari
Author: swader
Author: s_molinari
Author: swader
Author: s_molinari
Author: TomB
Author: s_molinari
Author: TomB
Author: Wolf_22
Author: swader
Author: swader
Author: s_molinari
*/

文章或产品实体可以包含讨论实体。通过在文章或产品实体上使用getDiscussion访问它，并像通常那样使用（见上文）。

自定义API

使用方法与所有其他API相同。只有两个区别

在创建自定义API调用时，您需要传递API名称
它总是返回通配符实体，这些实体基本上只是包含返回数据的值对象。它们定义了__call和__get魔术方法，因此它们的属性与其他实体一样易于访问，但没有自动完成功能。

以下是我自己的自定义API的使用示例，用于在SitePoint上获取作者个人资料

$diffbot = new Diffbot('my_token');
$customApi = $diffbot->createCustomAPI('http://sitepoint.com/author/bskvorc', 'authorFolioNew');

$return = $customApi->call();

foreach ($return as $wildcard) {
    dump($wildcard->getAuthor()); // Bruno Skvorc
    dump($wildcard->author); // Bruno Skvorc
}

当然，您可以轻松扩展基本的自定义API类，并创建自己的API，以及添加自己的实体，使它们与返回的数据完美匹配。所有这些内容都将在未来的教程中介绍。

Crawlbot和批量API

库中已添加基本的Crawlbot支持。要了解Crawlbot是什么，以及它是如何和为什么这样做，请参阅这里。我还建议阅读Crawlbot API文档和Crawlbot支持主题，这样您可以不受以下代码的困扰，直接深入使用。

简而言之，Crawlbot爬取一组种子URL以获取链接（即使传递给它作为种子URL的子域名，它也会遍历整个主域名和它能够找到的所有其他子域名），然后使用您定义的API（默认情况下选择分析API）处理它找到的所有页面。

所有爬取/批量作业列表

您可以通过以下方式获取所有爬取/批量作业的联合列表：

$diffbot = new Diffbot('my_token');
$jobs = $diffbot->crawl()->call();

这将返回所有爬取和批量作业的集合。每种类型都由其自己的类表示：JobCrawl和JobBulk。请注意，作业仅包含有关作业的信息——不是数据。要获取作业的数据，请使用downloadUrl方法获取数据集的URL。

$url = $job->downloadUrl("json");

爬取作业：创建爬取作业

请参阅内联注释以获取逐步说明。

// Create new diffbot as usual
$diffbot = new Diffbot('my_token');

// The crawlbot needs to be told which API to use to process crawled pages. This is optional - if omitted, it will be told to use the Analyze API with mode set to auto.
// The "crawl" url is a flag to tell APIs to prepare for consumption with Crawlbot, letting them know they won't be used directly.
$url = 'crawl';
$articleApi = $diffbot->createArticleAPI($url)->setDiscussion(false);

// Make a new crawl job. Optionally, pass in API instance
$crawl = $diffbot->crawl('sitepoint_01', $articleApi);

// Set seeds - seeds are URLs to crawl. By default, passing a subdomain into the crawl will also crawl other subdomains on main domain, including www.
$crawl->setSeeds(['http://sitepoint.com']);

// Call as usual - an EntityIterator collection of results is returned. In the case of a job's creation, only one job entity will always be returned.
$job = $crawl->call();

// See JobCrawl class to find out which getters are available 
dump($job->getDownloadUrl("json")); // outputs download URL to JSON dataset of the job's result

爬取作业：检查现有的爬取作业

要获取有关作业的数据（这将是与作业配置的数据——其标志——而不是结果！），请使用与创建新作业时完全相同的做法，只是没有API和种子。

$diffbot = new Diffbot('my_token');

$crawl = $diffbot->crawl('sitepoint_01');

$job = $crawl->call();

dump($job->getDownloadUrl("json")); // outputs download URL to JSON dataset of the job's result

爬取作业：修改现有的爬取作业

虽然无法在创建后更改爬取作业的配置，但您仍然可以对其进行一些操作。

假设您已经像上面的检查部分那样获取了$crawl实例，您可以进行以下操作

// Force start of a new crawl round manually
$crawl->roundStart();

// Pause or unpause (0) a job
$crawl->pause();
$crawl->pause(0)

// Restart removes all crawled data but keeps the job (and settings)
$crawl->restart();

// Delete a job and all related data
$crawl->delete();

请注意，在这些方法之后不需要发出call()。

如果您想提取这些即时调用动作生成的API调用URL，请传递参数false，如下所示

$crawl->delete(false);

然后您可以保存URL以供方便使用，并在准备好执行时调用call（如果需要的话）。

$url = $crawl->buildUrl();
$url->call();

搜索API

搜索API用于快速搜索通过批量或爬取API获取的数据。

$diffbot = new Diffbot('my_token');
$search = $diffbot->search('author:"Miles Johnson" AND type:article')->call();


foreach ($search as $article) {
    echo $article->getTitle();
}

使用搜索API的setCol方法仅针对特定集合进行目标定位——否则，将搜索您令牌的所有集合。

测试

只需在克隆项目的根目录中运行PHPUnit。一些调用需要互联网连接（请参阅tests/Factory/EntityTest）。

phpunit

添加实体测试

我将为每套5个新的实体测试支付10美元，每套提交经过验证——优惠有效，直到我觉得已经覆盖了足够的使用案例。（即不要一次性提交1500个，我一次无法支付这么多）。

如果您想通过添加实体测试来做出贡献，我建议遵循以下程序

选择您想要为其添加测试的API。例如，产品API。

在一个刮板如index.php中构建URL

$diffbot = new Diffbot('my_token');
$url = $diffbot
    ->createProductAPI('http://someurl.com')
    ->setMeta(true)
    ->...(insert other config methods here as desired)...
    ->buildUrl();
echo $url;

获取URL并将其粘贴到REST客户端如Postman或您的浏览器中。您将获得Diffbot的响应。请保持打开状态以供参考。
将此响应下载到JSON文件中。最好下载到tests/Mocks/Products/[date]/somefilename.json，就像其他测试一样。这可以通过在终端/命令行中执行curl "[url] > somefilename.json"轻松完成。
进入适当的测试文件夹。在这种情况下，tests/Entity，打开ProductTest.php。注意文件是如何添加到要测试的文件批次的。每个提供者都有其引用，以及要测试的方法应该产生的值。慢慢遍历每个测试方法，并添加您的文件。使用第3步中获得的JSON中的值。
运行 phpunit tests/Entity/ProductTest.php 来测试此文件（比整个测试套件更快）。如果测试通过，请发送PR :)

如果您也想创建自己的测试类，那当然也可以，不需要扩展项目中包含的类。只需应用整个流程，而不是扩展现有的 ProductTest 类，创建一个新的类。

添加其他测试

其他测试没有具体的说明，请根据您的理解进行贡献。只需尽量减少实际远程调用 - 我们不是在测试API本身（即Diffbot），我们在测试这个库。如果库能够从错误的API响应中准确解析值，例如，由于Diffbot当前存在bug，那也是可以的 - 库是正常工作的！

贡献

请参阅 CONTRIBUTING 以获取详细信息，以及 TODO 以获取想法。

致谢

布鲁诺·斯克沃尔茨

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

swader / diffbot-php-client

维护者

详细信息