README

PHP Twitter 库

[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/mfrost503/wheedle/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/mfrost503/wheedle/?branch=master) [![Build Status](https://scrutinizer-ci.com/g/mfrost503/wheedle/badges/build.png?b=master)](https://scrutinizer-ci.com/g/mfrost503/wheedle/build-status/master)

此库目前处于开发中，随着构建的进行将提供更多示例！

Wheedle 以一种通用的方式与 Twitter API 交互。使用 Guzzle 和 Snaggle 构建，你无需担心那些讨厌的 OAuth 1 签名。开始使用非常简单，只需传递你的令牌。

以下是一个如何轻松开始的示例！

便捷类方法
- 推文
- 直接消息
直接客户端使用
异常

基础

此库是便捷方法和基于 Guzzle 的直观 HTTP 客户端的平衡。通过利用 Guzzle 和 Snaggle，我们能够最小化开始对 Twitter API 进行身份验证请求所需的设置。Twitter API 的几乎所有端点都可能为您提供额外的选项。如果该特定端点有便捷方法，则会提供选项，但是您可能需要查阅 Twitter API 文档以获取有关您特定端点的更多信息。

目标是减轻处理 Twitter API 和其他不提供您所需功能的包装器和库的痛苦。我们旨在提供尽可能多的便捷性和易用性。如果您看到任何不正确或不完善的地方，贡献（问题、拉取请求、功能请求）总是受欢迎的。

便捷类方法

推文

Tweet 类将允许您检索和发布推文（或状态）。

检索

要检索推文，您需要知道推文的 ID，并将其作为参数传递给检索方法。

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);

try {

    $data = $tweet->retrieve(123456);

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

您可以可选地传递一个参数数组以获取您所需的内容，对于检索，参数如下：

trim_user 布尔值 当为 true 时，返回仅包含数字 ID 的用户对象
include_my_retweet 布尔值 当为 true 时，任何被认证用户 RT 的推文都将包含 current_user_retweet 节点
include_entities boolean entities 节点将在设置为 false 时被排除

这些参数完全可选，因此您可以包含所有或全部不包含

提及

要检索提及认证用户（@yourhandle）的推文集合，您可以使用 retrieveMentions 方法。

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);

try {

    $data = $tweet->retrieveMentions();

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

此方法的可选参数如下：

count 整数返回推文数量，最多 200 条
since_id 整数返回 ID 比提供的 ID 更新的结果
max_id int 返回ID早于提供ID的结果
trim_user boolean 当为true时，返回仅包含ID的用户对象
contributor_details boolean 当为true时，增强响应中的贡献者元素
include_entities boolean 当设置为false时，将排除实体节点

首页时间线

检索所有关注用户的推文集合

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);
try {

    $data = $tweet->retrieveHomeTimeline();

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

此方法的可选参数如下：

count 整数返回推文数量，最多 200 条
since_id 整数返回 ID 比提供的 ID 更新的结果
max_id int 返回ID早于提供ID的结果
trim_user boolean 当为true时，返回仅包含ID的用户对象
contributor_details boolean 当为true时，增强响应中的贡献者元素
include_entities boolean 当设置为false时，将排除实体节点

用户时间线

检索所有您的推文的时序

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);

try {

    $data = $tweet->retrieveUserTimeline();

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

此方法的可选参数如下：

count 整数返回推文数量，最多 200 条
since_id 整数返回 ID 比提供的 ID 更新的结果
max_id int 返回ID早于提供ID的结果
trim_user boolean 当为true时，返回仅包含ID的用户对象
contributor_details boolean 当为true时，增强响应中的贡献者元素
include_entities boolean 当设置为false时，将排除实体节点

我的推文 - 被其他人转发的

检索被其他用户转发的推文列表

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);

try {

    $data = $tweet->retrieveMyRetweets();

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

此方法的可选参数如下：

count 整数返回推文数量，最多 200 条
since_id 整数返回 ID 比提供的 ID 更新的结果
max_id int 返回ID早于提供ID的结果
trim_user boolean 当为true时，返回仅包含ID的用户对象
include_user_entities boolean 当设置为false时，将排除用户实体节点
include_entities boolean 当设置为false时，将排除实体节点

检索转推

检索单个推文的所有转推账户。

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);

try {

    $data = $tweet->retrieveRetweets(12345324);

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

此方法的可选参数如下：

count 整数返回推文数量，最多 200 条
trim_user boolean 当为true时，返回仅包含ID的用户对象

发送推文

创建新的推文并将其发布到您的时间轴

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);

try {

    $data = $tweet->create(['status' => 'This is a brand new tweet']);

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

此方法的可选参数如下：

in_reply_to_status_id int 您要回复的推文ID，必须@提及原始作者
possibly_sensitive boolean 当推文包含裸露、暴力或其他令人厌恶的内容时，应设置此选项
lat float 纬度
long float 经度
place_id string 世界上某个地方
display_coordinates boolean 当为true时，将在推文发送的确切坐标上放置一个标记
trim_user boolean 当为true时，返回仅包含ID的用户对象
media_ids string 要关联到推文的媒体ID列表

转推现有推文

将推文转发到您的时间轴

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);

try {

    $data = $tweet->retweet(12312432);

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

此方法的可选参数如下：

trim_user boolean 当为true时，返回仅包含ID的用户对象

删除现有推文

我们都会犯错误，对吧？以下是删除这些错误之一的方法...

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$tweet = new Tweet($client);

try {

    $data = $tweet->delete(12312432);

} catch (RuntimeException $e) {
    // handle Runtime Exception
} catch (RateLimitExceededException $e) {
    // handle rate limit exceeded exception
} catch (UnauthorizedRequestException $e) {
    // handle unauthorized request
}

此方法的可选参数如下：

trim_user boolean 当为true时，返回仅包含ID的用户对象

直接客户端使用

便捷方法非常棒，它们需要一点额外的时间来设置，但确实可以使访问API变得更加容易。现实是，并不是每个端点都会有便捷方法来覆盖，所以本节将要详细介绍如何使用 TwitterClient 来进行所有必要的调用。

如果我们看一个简单的例子，应该很容易看出这些调用是如何制作的。假设我们想检索ID为 1234567 的推文。显然，使用便捷类和方法，我们只需要实例化一个新的 Tweet 实例，然后调用带有id的检索方法。使用客户端，几乎同样简单。

<?php
use Snaggle\Client\Credentials\AccessCredentials;
use Snaggle\Client\Credentials\ConsumerCredentials;
use Wheedle\TwitterClient;
use Wheedle\Tweet;
use Wheedle\Exceptions\RateLimitExceededException;
use Wheedle\Exceptions\UnauthorizedRequestException;
use \RuntimeException;

$accessToken = new AccessCredentials('YOUR_ACCESS_TOKEN', 'YOUR_ACCESS_SECRET');

$consumerToken = new ConsumerCredentials('YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

$client = new TwitterClient($accessToken, $consumerToken);

$status = $client->get('statuses/show/1234567.json')

当然，我们仍然可以向这个调用添加可选参数，所以如果我们看看上面的 $client->get 调用，我们可以演示添加这些参数是多么简单。

$params = ['trim_user' => true, 'include_entities' => true];
$status = $client->get('statuses/show/1234567.json', $params);

作为选择，您也可以使用 http_build_query 自己构建查询字符串，但是 TwitterClient::get 和 TwitterClient::post 接口被构建成可以相同方式使用。还重要的是要注意，便捷方法将删除该端点不支持的所有选项。直接使用客户端时，您必须确保所有使用的可选参数对该端点是可用的。

使用客户端需要对Twitter API端点的工作方式有一定的了解，但阅读文档应该会使一切变得非常容易理解。使用此方法会抛出异常，就像便捷方法一样，所以您会得到相同的目标异常，无论您选择哪种方法。

异常

Wheedle有几种不同的异常类型可能会抛出。这些异常将指示特定调用无法正确完成。调用失败的原因有很多，例如：令牌无效、超过配额或尝试对不存在的资源进行调用。以下是所有可能抛出的异常的描述。

RateLimitExceededException

当特定访问令牌在指定时间段内超过允许的调用次数时，会抛出 RateLimitExceededException。需要注意的是，调用次数和持续时间是由Twitter设置的并维护的。这个异常通常与HTTP状态码 429 Too Many Requests 有关。

UnauthorizedRequestException

当尝试访问不属于当前凭据的访问令牌/密钥的资源时，会抛出UnauthorizedRequestException异常。此异常最常见的原因可能是令牌或令牌密钥输入错误，但它也用于指示已认证的用户没有访问他们尝试访问的资源。此异常通常与HTTP状态码401未授权相关。

MissingResourceException

当调用一个没有资源的端点时，会抛出MissingResourceException异常。这可能是因为ID输入错误、拼写错误或其他一些文书错误。始终检查并确保您正确地输入了端点及其后续可选参数非常重要。这对应于HTTP状态码404未找到。

TooManyCooksException

TooManyCooksException主要是为了有趣而加入的。它不是必须使用的，也不会直接抛出。它可以在捕获块中用来代替RateLimitExceededException。明确地说，我实际上不推荐使用此异常。它描述性较差，可能会引起混淆。我加入它是因为我想，并且觉得很有趣。RateLimitExceededException也将是一种TooManyCooksException类型。您可以根据自己的需要进行处理。

mfrost503 / wheedle

维护者

详细信息

README

PHP Twitter 库

基础

便捷类方法

推文

检索

提及

首页时间线

用户时间线

我的推文 - 被其他人转发的

检索转推

发送推文

转推现有推文

删除现有推文

直接客户端使用

异常

RateLimitExceededException

UnauthorizedRequestException

MissingResourceException

TooManyCooksException