twitter

PHP 版 Twitter

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="AtymicTwitterServiceProviderLaravelServiceProvider"

 /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 客户端的实例。使用Twitter::forApiV1()从v2客户端获取v1实例也是如此。

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

功能

推特 API v1.1

帐户

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

账户活动（高级）

• setWebhook($env, $url) - 为给定环境中的所有事件类型注册 webhook url。
• crcHash($crcToken) - 从给定的 CRC 令牌和消费者密钥返回 HMAC SHA-256 哈希值。您需要将其返回到您的网络钩子上（更多信息）。
• getWebhooks($env) - 返回给定环境（或所有环境，如果未提供）的 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() - 发布一个新的 message_create 事件，从而导致从身份验证用户发送到指定用户的直接消息。如果成功则返回一个事件。支持通过可选的快速回复和媒体附件发布私信。

最喜欢的

• getFavorites() - 返回由身份验证用户或指定用户收藏的 20 条最新推文。
• destroyFavorite() - 取消收藏 ID 参数中指定的身份验证用户状态。成功时以请求的格式返回不喜欢的状态。
• postFavorite() - 收藏 ID 参数中指定的状态作为身份验证用户。成功时返回收藏夹状态。

友谊

• getNoRters() - 返回当前经过身份验证的用户不希望从中接收转发的 user_ids 集合。
• 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() - 搜索可以附加到状态/更新的地点。给定纬度和经度对、IP 地址或名称，此请求将返回所有有效地点的列表，这些地点可在更新状态时用作 place_id。
• getGeoSimilar() - 定位给定坐标附近名称相似的地点。从概念上讲，您将使用此方法来获取要首先选择的已知地点的列表。然后，如果所需地点不存在，请向 POST geo/place 发出请求以创建一个新地点。响应中包含的令牌是能够创建新地点所需的令牌。

帮助

• postSpam() - 向 Twitter 报告指定用户为垃圾邮件帐户。另外，代表经过身份验证的用户执行相当于 POST 块/创建的操作。
• 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 或屏幕名称列表，将多个成员添加到列表中。经过身份验证的用户必须拥有该列表才能向其中添加成员。请注意，列表的成员不能超过 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 的小部件 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() - 将身份验证用户的 ID 参数中指定的用户静音。
• unmuteUser() - 对身份验证用户的 ID 参数中指定的用户取消静音。
• mutedUserIds() - 返回验证用户已静音的数字用户 ID 数组。
• mutedUsers() - 返回验证用户已静音的用户对象数组。
• getSuggesteds() - 访问 Twitter 建议用户列表的给定类别中的用户。
• getSuggestions() - 访问 Twitter 的建议用户列表。这将返回建议的用户类别列表。该类别可以在 GET users / suggest / :slug 中使用来获取该类别中的用户。
• getSuggestedsMembers() - 访问 Twitter 建议用户列表的给定类别中的用户，如果他们不是受保护的用户，则返回他们的最新状态。

推特 API v2

推文查找

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

搜索推文

• searchRecent() - 最近的搜索端点返回过去 7 天内与搜索查询匹配的推文。

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

  注意：此端点仅适用于那些被批准用于学术研究产品轨道的人。

时间表

• userTweets() - 返回由单个用户组成的推文，由请求的用户 ID 指定。默认情况下，每个请求都会返回最近的 10 条推文。使用分页，可以检索最近的 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/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 作为字符串传递，而不是作为布尔值传递。布尔值将被转换为 Twitter 忽略的1 。

这还假设您已正确设置 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，您需要使用 CRC 令牌从 Webhook URL 响应中返回哈希值（更多信息）。

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