README

支持 Laravel 10.x, 11.x（以及发布的新版本）。也支持通过 PHP-DI 其他框架（或者您也可以通过 PR 添加对您框架的支持）。

您需要在 应用程序管理 中创建应用程序并创建您的访问令牌。

安装

composer require atymic/twitter:^3.0 -W

Laravel 配置

只需在您的 .env 中设置以下环境变量。

TWITTER_CONSUMER_KEY=
TWITTER_CONSUMER_SECRET=
TWITTER_ACCESS_TOKEN=
TWITTER_ACCESS_TOKEN_SECRET=
TWITTER_API_VERSION=

高级 Laravel 配置

运行 php artisan vendor:publish --provider="Atymic\Twitter\ServiceProvider\LaravelServiceProvider"

/config/twitter.php

版本

3.x

3.x 是当前主版本，与 2.x 不兼容。

请参阅 UPGRADE.md 中的迁移指南。

2.x

2.x 已停止维护。我们不再接受错误修复，请升级到 3.x

用法

输出格式

您可以选择三种不同的输出格式。默认情况下，API v1 响应将以对象返回，而 API v2 响应将以 JSON 返回。要更改此设置，请在传递给任何方法的参数中使用 response_format 选项。

response_format : object|json|array (v1 default:object) (v2 default:json)

Twitter API 版本

要将默认 Twitter API 版本设置为 v2 而不是默认的 v1.1，请在您的 .env 中将 TWITTER_API_VERSION 设置为 2。

如果您已将 v1.1 API 设置为默认值，您可以使用 Twitter::forApiV2() 获取 v2 客户端的实例。同样，要从 v2 客户端获取 v1 实例，请使用 Twitter::forApiV1()。

在 v1 或 v2 客户端实例上调用 Twitter::forApiV1() 是安全的。

函数

Twitter API v1.1

账户

• getSettings() - 返回认证用户的设置（包括当前趋势、地理信息和睡眠时间信息）。
• getCredentials()
• postSettings() - 更新认证用户的设置。
• postSettingsDevice() - 为认证用户设置 Twitter 传送更新到的设备。将设备参数发送为 none 将禁用 SMS 更新。
• postProfile() - 设置用户可以在其设置页面“账户”选项卡下设置的某些值。只有指定的参数将更新。
• postBackground() - 更新认证用户的个人资料背景图片。此方法也可以用来启用或禁用个人资料背景图片。
• postProfileImage() - 更新认证用户的个人资料图片。请注意，此方法期望原始的多部分数据，而不是指向图片的 URL。
• destroyUserBanner() - 删除上传的个人资料横幅。成功时返回 HTTP 200。
• postUserBanner() - 代表认证用户上传个人资料横幅。为了获得最佳效果，请在上传个人资料对象中的 profile_banner_url 节点上上传个人资料横幅 URL。

账户活动（高级版）

• setWebhook($env, $url) - 在给定环境中为所有事件类型注册 webhook URL。
• crcHash($crcToken) - 返回给定CRC令牌和消费者密钥的HMAC SHA-256哈希。您需要在webhook中返回此信息（更多信息）。
• getWebhooks($env) - 返回给定环境的webhook URL（如果没有提供环境，则返回所有环境的webhook URL）及其认证应用的状况。
• updateWebhooks($env, $webhookId) - 触发给定环境的webhook的所有活动的挑战响应检查（CRC）。如果检查成功，则返回true并将webhook的状态设置为有效，重新启用它。
• destroyWebhook($env, $webhookId) - 从提供应用的全部活动配置中删除webhook。成功时返回true。
• setSubscriptions($env) - 将提供的应用程序订阅到提供的环境的所有事件的所有消息类型。成功时返回true。
• getSubscriptions($env) - 如果提供用户上下文具有与提供应用相关的活动订阅，则返回true。
• getSubscriptionsCount() - 返回您账户上所有活动的当前活动订阅数量。
• getSubscriptionsList($env) - 返回当前所有活动类型订阅的列表。
• destroyUserSubscriptions($env, $userId) - 从环境中停用指定用户ID的订阅。成功时返回true。

Block

• getBlocks() - 返回认证用户所屏蔽的用户对象集合。
• getBlocksIds() - 返回认证用户所屏蔽的数字用户ID数组。
• postBlock() - 屏蔽指定的用户，使其无法关注认证用户。此外，被屏蔽用户不会在认证用户的提及或时间线中显示（除非被其他用户转发）。如果存在关注或朋友关系，则会销毁。
• destroyBlock() - 为认证用户取消屏蔽ID参数中指定的用户。成功时返回未屏蔽的用户，格式根据请求而定。如果在屏蔽生效之前存在关系，则不会恢复。

DirectMessage

• getDm() - 返回单个直接消息事件，通过ID参数指定。
• getDms() - 返回过去30天内所有直接消息事件（包括发送和接收），按倒序排列。
• destroyDm() - 销毁在必需ID参数中指定的直接消息。认证用户必须是该指定直接消息的接收者。
• postDm() - 发布一个新消息_create事件，导致从认证用户向指定用户发送直接消息。成功时返回事件。支持发布带有可选快速回复和媒体附件的直接消息。

Favorite

• getFavorites() - 返回认证用户或指定用户最近20条赞过的推文。
• destroyFavorite() - 取消对ID参数中指定的状态作为认证用户的赞。成功时返回未赞过的状态，格式根据请求而定。
• postFavorite() - 对ID参数中指定的状态作为认证用户进行点赞。成功时返回赞过的状态。

Friendship

• getNoRters() - 返回当前认证用户不希望接收其转发的推文的所有用户ID集合。
• getFriendsIds() - 返回每个关注指定用户的用户的用户ID的游标集合。
• getFollowersIds() - 返回每个关注指定用户的用户的用户ID的游标集合。
• getFriendshipsIn() - 返回每个向认证用户发送关注请求的用户的数字ID集合。
• getFriendshipsOut() - 返回认证用户有未完成关注请求的每个受保护用户的数字ID集合。
• postFollow() - 允许认证用户关注ID参数中指定的用户。
• postUnfollow() - 允许认证用户取消关注ID参数中指定的用户。
• postFollowUpdate() - 允许用户启用或禁用指定用户的转发和设备通知。
• getFriendships() - 返回两个任意用户之间关系的详细信息。
• getFriends() - 返回指定用户关注的每个用户的用户对象的游标集合（也称为他们的“朋友”）。
• getFollowers() - 返回关注指定用户的用户对象的游标集合。
• getFriendshipsLookup() - 返回认证用户与逗号分隔的最多100个screen_names或user_ids提供的列表之间的关系。连接值可以是：following、following_requested、followed_by、none、blocking、muting。

地理信息

• getGeo() - 返回关于已知地点的所有信息。
• getGeoReverse() - 给定纬度和经度，搜索最多20个可以用作更新状态时的place_id的地点。
• getGeoSearch() - 搜索可以附加到statuses/update的地点。给定纬度和经度对、IP地址或名称，此请求将返回所有有效地点列表，这些地点可以用作更新状态时的place_id。
• getGeoSimilar() - 定位与给定坐标相似的地点。从概念上讲，您会使用此方法首先获取一个已知地点列表进行选择。然后，如果所需的地点不存在，请发送POST geo/place请求创建一个新的地点。响应中包含的令牌是创建新地点所需的令牌。

帮助

• postSpam() - 将指定用户报告为Twitter的垃圾邮件账户。此外，代表认证用户执行POST blocks / create的等效操作。
• getHelpConfiguration() - 返回Twitter当前使用的配置，包括不是用户名的twitter.com别名、最大照片分辨率和t.co URL长度。
• getHelpLanguages() - 返回Twitter支持的语言列表以及Twitter支持的语言代码。
• getHelpPrivacy() - 返回Twitter的隐私政策。
• getHelpTos() - 返回Twitter的服务条款。注意：这些条款与开发者政策不同。
• getAppRateLimit() - 返回属于指定资源家族的方法的当前速率限制。

列表

• getLists() - 返回认证用户或指定用户订阅的所有列表，包括他们自己的列表。使用user_id或screen_name参数指定用户。如果没有提供用户，则使用认证用户。
• getListStatuses() - 返回指定列表成员发布的推文的时间线。默认包含转发。使用include_rts=false参数省略转发。
• destroyListMember() - 从列表中删除指定的成员。认证用户必须是列表的所有者才能从列表中删除成员。
• getListsMemberships() - 返回指定用户被添加到的列表。如果未提供user_id或screen_name，则返回认证用户的成员资格。
• getListsSubscribers() - 返回指定列表的订阅者。如果认证用户是指定列表的所有者，则仅显示私人列表订阅者。
• postListSubscriber() - 将认证用户订阅到指定列表。
• getListSubscriber() - 返回指定列表的订阅者。如果认证用户是列表的所有者，则仅显示私人列表订阅者。
• destroyListSubscriber() - 从指定列表中取消订阅认证用户。
• postListCreateAll() - 通过指定用逗号分隔的成员ID或屏幕名列表，向列表中添加多个成员。认证用户必须拥有该列表才能向其中添加成员。请注意，列表不能超过5,000个成员，并且使用此方法一次最多只能向列表中添加100个成员。
• getListMember() - 检查指定用户是否是指定列表的成员。
• getListMembers() - 返回指定列表的成员。只有认证用户拥有指定列表时，才会显示私人列表成员。
• postListMember() - 向列表中添加成员。认证用户必须拥有列表才能向其中添加成员。请注意，列表不能超过5,000个成员。
• destroyList() - 删除指定的列表。认证用户必须拥有列表才能删除它。
• postListUpdate() - 更新指定的列表。认证用户必须拥有列表才能更新它。
• postList() - 为认证用户创建一个新的列表。请注意，每个账户最多只能创建20个列表。
• getList() - 返回指定的列表。只有认证用户拥有指定列表时，才会显示私人列表。
• getListSubscriptions() - 获取指定用户订阅的列表集合，默认每页20个列表。不包括用户的个人列表。
• destroyListMembers() - 通过指定用逗号分隔的成员ID或屏幕名列表，从列表中删除多个成员。认证用户必须拥有列表才能从中删除成员。请注意，列表不能超过500个成员，并且使用此方法一次最多只能删除100个成员。
• getListOwnerships() - 返回指定Twitter用户拥有的列表。只有认证用户也是列表的所有者时，才会显示私人列表。

媒体

• uploadMedia() - 将媒体（图片）上传到Twitter，用于推文或Twitter托管卡。

搜索

• getSearch() - 返回与指定查询匹配的相关推文集合。
• getSavedSearches() - 返回认证用户的已保存搜索查询。
• getSavedSearch() - 获取表示给定ID的已保存搜索的信息。请求已保存搜索ID的认证用户必须是该搜索的所有者。
• postSavedSearch() - 为认证用户创建一个新的已保存搜索。用户最多只能有25个已保存搜索。
• destroySavedSearch() - 删除认证用户的已保存搜索。请求删除已保存搜索ID的认证用户必须是该搜索的所有者。

状态

• getMentionsTimeline() - 返回认证用户最近的20条提及（包含用户@screen_name的推文）。
• getUserTimeline() - 返回由screen_name或user_id参数指定的用户最近发布的推文集合。
• getHomeTimeline() - 返回认证用户及其关注的用户最近发布的推文和转发的推文集合。主时间线是大多数用户与Twitter服务互动的核心。 *
• getRtsTimeline() - 返回认证用户创作的最近被其他人转发的推文。
• getRts() - 返回指定id参数的推文最近的100条转发。
• getTweet() - 返回单个推文，指定id参数。推文的作者也会嵌入到推文中。
• destroyTweet() - 销毁由必需的ID参数指定的状态。认证用户必须是该状态的作者。如果成功，返回销毁的状态。
• postTweet() - 更新认证用户的当前状态，也称为发推。
• postRt() - 转发一条推文。返回包含转发详情的原始推文。
• getOembed() - 以oEmbed兼容的格式返回一个推文，该推文由推文网页URL或推文ID指定。当页面上包含Twitter的小部件JavaScript时，返回的HTML片段将自动被识别为嵌入的推文。
• getRters() - 返回最多100个用户ID的集合，这些用户ID属于转发id参数指定的推文的人。
• getStatusesLookup() - 返回最多100条推文的完全填充的推文对象，这些推文由逗号分隔的id参数值指定。

趋势

• getTrendsPlace() - 如果特定WOEID有趋势信息，则返回该WOEID的前10个热门话题。
• getTrendsAvailable() - 返回Twitter有趋势话题信息的地点。
• getTrendsClosest() - 返回Twitter有趋势话题信息的地点，这些地点与指定的地点最接近。

用户

• getUsersLookup() - 返回最多100个用户的完全填充的用户对象，这些用户通过user_id和/或screen_name参数指定的逗号分隔值传递。
• getUsers() - 返回由必需的user_id或screen_name参数指定的用户的各种信息。如果可能，将返回作者的最近推文。
• getUsersSearch() - 提供一个简单、基于相关性的搜索界面，用于Twitter上的公共用户账户。尝试通过主题兴趣、全名、公司名称、位置或其他标准进行查询。不支持精确匹配搜索。
• getUserBanner() - 返回指定用户个人资料横幅的可用的尺寸变化映射。如果用户未上传个人资料横幅，将提供HTTP 404。此方法可以用作在个人资料对象中返回的profile_banner_url上进行字符串操作，如个人资料图片和横幅中所述。
• muteUser() - 对于认证用户，静音ID参数中指定的用户。
• unmuteUser() - 对于认证用户，取消静音ID参数中指定的用户。
• mutedUserIds() - 返回认证用户静音的数字用户ID数组。
• mutedUsers() - 返回认证用户静音的用户对象数组。
• getSuggesteds() - 访问Twitter推荐用户列表中给定类别的用户。
• getSuggestions() - 访问Twitter的推荐用户列表。这返回推荐用户类别的列表。可以使用此类别在GET users / suggestions / :slug中获取该类别的用户。
• getSuggestedsMembers() - 访问Twitter推荐用户列表中给定类别的用户，如果它们不是受保护用户，则返回他们的最新状态。

Twitter API v2

推文查找

• getTweet() - 返回由请求ID指定的单个推文的多种信息。
• getTweets() - 返回由请求ID或ID列表指定的推文的多种信息。

搜索推文

• searchRecent() - 最近搜索端点返回匹配搜索查询的最后七天的推文。

• searchAll() - 完整存档搜索端点返回匹配搜索查询的公共推文的完整历史记录；自第一条推文于2006年3月26日创建以来。

  注意：此端点仅对批准为学术研究产品轨道的人可用。

时间线

• userTweets() - 返回由请求用户ID指定的单个用户撰写的推文。默认情况下，每次请求返回最新的十个推文。使用分页可以检索最新的3,200条推文。
• userMentions() - 返回提及指定用户ID的推文。默认情况下，每次请求返回最近的10条推文。使用分页，最多可以检索到最近的800条推文。

过滤流

• getStreamRules() - 返回在流式传输端点当前激活的规则列表，可以是列表或单个规则。
• postStreamRules() - 添加或删除流中的规则。
• getStream() - 根据特定的过滤规则实时流式传输推文。

样本流

• getSampledStream() - 实时流式传输大约1%的所有推文。

隐藏回复

• hideTweet() - 隐藏或显示对推文的回复。

推文计数

• countRecent() - 接收过去7天内与查询匹配的推文数量。

• countAll() - 接收与查询匹配的推文数量。

  注意：仅通过学术研究产品轨道可用。

辅助函数

Linkify：将URL、@用户名、标签转换为链接。$tweet的类型可以是对象、数组或文本。通过发送对象或数组，该方法还会扩展链接（t.co）。

Twitter::linkify($tweet);

Ago：将日期转换为差异（2小时前）

Twitter::ago($timestamp);

LinkUser：通过用户对象（如$tweet->user）或id/字符串生成特定用户的链接。

Twitter::linkUser($user);

LinkTweet：生成特定推文的链接。

Twitter::linkTweet($tweet);

示例

返回由screen_name或user_id参数指定的用户最近发布的推文集合。

Route::get('/userTimeline', function()
{
	return Twitter::getUserTimeline(['screen_name' => 'thujohn', 'count' => 20, 'response_format' => 'json']);
});

返回认证用户及其关注的用户最近发布的推文和转推文的集合。

Route::get('/homeTimeline', function()
{
	return Twitter::getHomeTimeline(['count' => 20, 'response_format' => 'json']);
});

返回认证用户最近的X条提及（包含用户的@screen_name）。

Route::get('/mentionsTimeline', function()
{
	return Twitter::getMentionsTimeline(['count' => 20, 'response_format' => 'json']);
});

更新认证用户的当前状态，也称为推文。

Route::get('/tweet', function()
{
	return Twitter::postTweet(['status' => 'Laravel is beautiful', 'response_format' => 'json']);
});

使用媒体更新认证用户的当前状态。

Route::get('/tweetMedia', function()
{
	$uploaded_media = Twitter::uploadMedia(['media' => File::get(public_path('filename.jpg'))]);
	return Twitter::postTweet(['status' => 'Laravel is beautiful', 'media_ids' => $uploaded_media->media_id_string]);
});

使用电子邮件获取用户凭据。

$credentials = Twitter::getCredentials([
    'include_email' => 'true',
]);

在上面的示例中，您需要将true作为字符串传递，而不是布尔值。布尔值将被转换为1，Twitter会忽略它。

这也假设您已经正确设置了Twitter的权限。在设置Twitter应用程序时，您必须选择'获取用户电子邮件'，仅传递值是不够的。

通过Twitter登录

use Atymic\Twitter\Facade\Twitter;

Route::get('twitter/login', ['as' => 'twitter.login', static function () {
    $token = Twitter::getRequestToken(route('twitter.callback'));

    if (isset($token['oauth_token_secret'])) {
        $url = Twitter::getAuthenticateUrl($token['oauth_token']);

        Session::put('oauth_state', 'start');
        Session::put('oauth_request_token', $token['oauth_token']);
        Session::put('oauth_request_token_secret', $token['oauth_token_secret']);

        return Redirect::to($url);
    }

    return Redirect::route('twitter.error');
}]);

Route::get('twitter/callback', ['as' => 'twitter.callback', static function () {
    // You should set this route on your Twitter Application settings as the callback
    // https://apps.twitter.com/app/YOUR-APP-ID/settings
    if (Session::has('oauth_request_token')) {
        $twitter = Twitter::usingCredentials(session('oauth_request_token'), session('oauth_request_token_secret'));
        $token = $twitter->getAccessToken(request('oauth_verifier'));

        if (!isset($token['oauth_token_secret'])) {
            return Redirect::route('twitter.error')->with('flash_error', 'We could not log you in on Twitter.');
        }

        // use new tokens
        $twitter = Twitter::usingCredentials($token['oauth_token'], $token['oauth_token_secret']);
        $credentials = $twitter->getCredentials();

        if (is_object($credentials) && !isset($credentials->error)) {
            // $credentials contains the Twitter user object with all the info about the user.
            // Add here your own user logic, store profiles, create new users on your tables...you name it!
            // Typically you'll want to store at least, user id, name and access tokens
            // if you want to be able to call the API on behalf of your users.

            // This is also the moment to log in your users if you're using Laravel's Auth class
            // Auth::login($user) should do the trick.

            Session::put('access_token', $token);

            return Redirect::to('/')->with('notice', 'Congrats! You\'ve successfully signed in!');
        }
    }

    return Redirect::route('twitter.error')
            ->with('error', 'Crab! Something went wrong while signing you up!');
}]);

Route::get('twitter/error', ['as' => 'twitter.error', function () {
    // Something went wrong, add your own error handling here
}]);

Route::get('twitter/logout', ['as' => 'twitter.logout', function () {
    Session::forget('access_token');

    return Redirect::to('/')->with('notice', 'You\'ve successfully logged out!');
}]);

Webhook

为了成功设置Webhook，您需要从Webhook URL返回一个使用CRC令牌的哈希值（更多信息）。

Route::post('twitter/webhook', ['as' => 'twitter.webhook', function(){
	if (request()->has('crc_token'))
		return response()->json(['response_token' => Twitter::crcHash(request()->crc_token)], 200);
	
	// Your webhook logic goes here
}]);

Twitter API v2示例

获取用户推文

// ...

use Atymic\Twitter\Twitter as TwitterContract;
use Illuminate\Http\JsonResponse;
use Twitter;

// ... 

public function userTweets(int $userId): JsonResponse
{
	$params = [
		'place.fields' => 'country,name',
		'tweet.fields' => 'author_id,geo',
		'expansions' => 'author_id,in_reply_to_user_id',
		TwitterContract::KEY_RESPONSE_FORMAT => TwitterContract::RESPONSE_FORMAT_JSON,
	];

	return JsonResponse::fromJsonString(Twitter::userTweets($userId, $params));
}

搜索推文

// ...
public function searchRecent(string $query): JsonResponse
{
    $params = [
        'place.fields' => 'country,name',
        'tweet.fields' => 'author_id,geo',
        'expansions' => 'author_id,in_reply_to_user_id',
        TwitterContract::KEY_RESPONSE_FORMAT => TwitterContract::RESPONSE_FORMAT_JSON,
    ];

    return JsonResponse::fromJsonString(Twitter::searchRecent($query, $params));
}
// ...

调用新添加的端点

由于Twitter API v2正在积极开发中，您可能需要调用我们上面在“函数”部分中没有明确记录的端点。以下是一个示例，说明您如何使用此包调用任何新添加的端点。这里我们使用新添加的“最近计数”端点。

// ...
$querier = \Atymic\Twitter\Facade\Twitter::forApiV2()
    ->getQuerier();
$result = $querier
    ->withOAuth2Client()
    ->get('tweets/counts/recent', ['query' => 'foo']);
// ...

调试

首先在配置文件中激活调试模式。

然后您可以访问logs()方法。

try
{
	$response = Twitter::getUserTimeline(['count' => 20, 'response_format' => 'array']);
}
catch (Exception $e)
{
	// dd(Twitter::error());
	dd(Twitter::logs());
}

dd($response);