README

Laravel 6.x, 7.x, 8.x (以及发布的新版本) 的 Twitter API。还支持通过 PHP-DI（或您也可以通过 PR 添加对您框架的支持）使用其他框架。

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

安装

composer require atymic/twitter

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。

使用方法

输出格式

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

format : object|json|array (default:object)

Twitter API 版本

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

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

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

函数

Twitter API v1.1

账户

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

阻止

• 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。

Geo

• 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或screen_name列表，将多个成员添加到列表中。认证用户必须是列表的所有者才能将其添加到列表中。注意，列表不能超过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兼容的格式返回由推文Web URL或推文ID指定的单个推文。当页面包含Twitter的widget JavaScript时，返回的HTML片段将自动被识别为嵌入式推文。
• getRters() - 返回最多100个用户ID的集合，这些用户ID属于转发指定id参数的推文的用户。
• getStatusesLookup() - 返回最多100条推文请求的完全填充的推文对象，由id参数传递的逗号分隔值指定。

趋势

• getTrendsPlace() - 如果有趋势信息，返回特定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() - 对认证用户指定的用户进行静音。
• unmuteUser() - 对认证用户指定的用户取消静音。
• 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() - 返回由请求的 user ID 指定的单个用户组成的推文。默认情况下，每次请求返回最新的十个推文。使用分页，可以检索最新的 3,200 个推文。
• userMentions() - 返回提及请求的 user ID 指定的单个用户的推文。默认情况下，每次请求返回最新的十个推文。使用分页，最多可以检索最新的 800 个推文。

过滤流

• getStreamRules() - 返回在流式传输端点当前激活的规则列表，无论是作为列表还是单独的规则。
• postStreamRules() - 向流添加或删除规则。
• getStream() - 根据一组特定的过滤规则实时流式传输推文。

样本流

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

隐藏回复

• hideTweet() - 隐藏或取消隐藏推文的回复。

辅助函数

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!');
}]);

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));
}
// ...

调试

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

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

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

dd($response);