README

适用于Laravel 10.x、11.x（以及随后的新版本）的Twitter API。也支持通过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为认证用户发送更新的设备。将设备参数发送为空将禁用短信更新。
• postProfile() - 设置用户在其设置页面“账户”选项卡下可以设置的某些值。只有指定的参数将更新。
• postBackground() - 更新认证用户的个人资料背景图片。此方法还可以用于启用或禁用个人资料背景图片。
• postProfileImage() - 更新认证用户的个人资料图片。请注意，此方法期望原始的多部分数据，而不是指向图片的URL。
• destroyUserBanner() - 删除认证用户的上传个人资料横幅。成功时返回HTTP 200。
• postUserBanner() - 代表认证用户上传个人资料横幅。为了获得最佳效果，请上传一个包含在他们的用户对象中的个人资料横幅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。

阻止

• getBlocks() - 返回被认证用户阻止的用户对象集合。
• getBlocksIds() - 返回被认证用户阻止的数字用户ID数组。
• postBlock() - 阻止指定的用户关注认证用户。此外，被阻止的用户不会出现在认证用户的提及或时间轴中（除非被其他用户转发）。如果存在关注或朋友关系，则将其销毁。
• destroyBlock() - 为认证用户取消指定ID参数中指定的用户的阻止。成功时，以请求的格式返回取消阻止的用户。如果阻止之前存在关系，则不会恢复。

直接消息

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

收藏

• getFavorites() - 返回认证用户或指定用户最近20个收藏的推文。
• destroyFavorite() - 取消收藏在ID参数中指定的状态。成功时，以请求的格式返回取消收藏的状态。
• postFavorite() - 将在ID参数中指定的状态作为认证用户的收藏。成功时返回收藏的状态。

友谊

• getNoRters() - 返回当前认证用户不希望接收转发推文的user_ids集合。
• getFriendsIds() - 返回跟随指定用户的每个用户的user IDs的游标集合。
• getFollowersIds() - 返回跟随指定用户的每个用户的user IDs的游标集合。
• 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 slugs（不是用户名）、最大照片分辨率和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或screen_names列表将多个成员添加到列表中。认证用户必须拥有列表才能将成员添加到列表中。注意，列表不能有超过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条提及（包含用户屏幕名的推文）。
• getUserTimeline() - 返回由screen_name或user_id参数指定的用户最近发布的推文集合。
• getHomeTimeline() - 返回认证用户和其关注的用户最近发布的推文和转发的推文集合。主时间线是大多数用户与Twitter服务互动的核心。 *
• getRtsTimeline() - 返回认证用户创作的最近被其他人转发的推文。
• getRts() - 返回由id参数指定的推文的100条最近转发的推文集合。
• getTweet() - 返回由id参数指定的单个推文。推文的作者也会嵌入推文中。
• destroyTweet() - 删除由必需ID参数指定的状态。认证用户必须是指定状态的作者。如果成功，将返回已删除的状态。
• postTweet() - 更新认证用户当前的状态，也称为发推。
• postRt() - 转发一条推文。返回带有转发详情嵌入的原始推文。
• getOembed() - 以oEmbed兼容的格式返回由推文Web URL或推文ID指定的单个推文。返回的HTML片段将自动被识别为嵌入推文，当页面上包含Twitter的小部件JavaScript时。
• getRters() - 返回最多100个用户ID，属于已转发由id参数指定的推文的用户。
• getStatusesLookup() - 根据ID参数传入的逗号分隔值，返回最多100条推文的完整 hydrated推文对象。

趋势

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

用户

• getUsersLookup() - 根据user_id和/或screen_name参数传入的逗号分隔值，返回最多100个用户的完整 hydrated用户对象。
• 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指定的单个用户的推文。默认情况下，每次请求返回最新的十个推文。使用分页，可以检索最新的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/string生成特定用户的链接。

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);