README

PHP Twitch Helix API Wrapper for Laravel 5+

⚠️ 2020年5月1日变更

自2020年5月1日起，Twitch要求所有请求必须包含有效的OAuth访问令牌。这可以通过使用客户端凭证流请求OAuth令牌来实现。

如果您自己处理，请确保通过配置条目oauth_client_credentials.auto_generate启用内置的访问令牌生成功能。

您需要通过配置或可用的设置器定义有效的客户端ID和客户端密钥！有关更多详细信息，请参阅完整配置。

安装

composer require romanzipp/laravel-twitch

配置

将配置复制到项目中

php artisan vendor:publish --provider="romanzipp\Twitch\Providers\TwitchServiceProvider"

将环境变量添加到您的 .env

TWITCH_HELIX_KEY=
TWITCH_HELIX_SECRET=
TWITCH_HELIX_REDIRECT_URI=http://localhost

如果您想使用Webhook传输方式使用EventSub，则必须定义一个密钥。此密钥是10到100个字符的字符串。

TWITCH_HELIX_EVENTSUB_SECRET=

示例

基本

$twitch = new romanzipp\Twitch\Twitch;

$twitch->setClientId('abc123');

// Get User by Username
$result = $twitch->getUsers(['login' => 'herrausragend']);

// Check, if the query was successful
if ( ! $result->success()) {
    return null;
}

// Shift result to get single user data
$user = $result->shift();

return $user->id;

设置器

$twitch = new romanzipp\Twitch\Twitch;

$twitch->setClientId('abc123');
$twitch->setClientSecret('abc456');
$twitch->setToken('abcdef123456');

$twitch = $twitch->withClientId('abc123');
$twitch = $twitch->withClientSecret('abc123');
$twitch = $twitch->withToken('abcdef123456');

OAuth令牌

$twitch = new romanzipp\Twitch\Twitch;

$twitch->setClientId('abc123');
$twitch->setToken('abcdef123456');

$result = $twitch->getUsers(['login' => 'herrausragend']);

OAuth客户端凭证流

自2020年5月1日起，每个请求都需要OAuth令牌，该令牌可以使用OAuth客户端凭证流发布。

use romanzipp\Twitch\Enums\GrantType;
use romanzipp\Twitch\Twitch;

$twitch = new Twitch;

$twitch->setClientId('abc123');
$twitch->setClientSecret('def123');
$twitch->setToken('abcdef123456');

$result = $twitch->getOAuthToken(null, GrantType::CLIENT_CREDENTIALS, ['user:read']);

if ( ! $result->success()) {
    return;
}

$accessToken = $result->data()->access_token;

分页

Twitch API返回一个包含分页结果的paginator字段，例如/streams、/follows或/games。要跳转到其他页面，必须将提供的游标附加到后续查询中，使用方向属性after或before。

在此示例中，我们将获取一系列流并使用提供的游标来切换到下一组或上一组数据。

❗️ 为防止无限循环或错误，请使用Result::hasMoreResults()方法检查是否有更多结果可用。

$twitch = new romanzipp\Twitch\Twitch;

// Page 1
$firstResult = $twitch->getStreams(['language' => 'de']);

// Page 2
$secondResult = $twitch->getStreams(['language' => 'de'], $firstResult->next());

// Page 1 (again)
$thirdResult = $twitch->getStreams(['language' => 'de'], $secondResult->back());

外观

use romanzipp\Twitch\Facades\Twitch;

Twitch::withClientId('abc123')->withToken('abcdef123456')->getUsers();

分页循环示例

此示例获取所有Twitch游戏并将它们存储到数据库中。

use romanzipp\Twitch\Twitch;

$twitch = new Twitch;

do {
    $nextCursor = null;

    // If this is not the first iteration, get the page cursor to the next set of results
    if (isset($result)) {
        $nextCursor = $result->next();
    }

    // Query the API with an optional cursor to the next results page
    $result = $twitch->getTopGames(['first' => 100], $nextCursor);

    foreach ($result->data() as $item) {
        // Process the games result data
    }

    // Continue until there are no results left
} while ($result->hasMoreResults());

插入用户对象

新API不包括用户对象，如followers或bits等端点。

[
  {
    "from_id": "123456",
    "to_id": "654321",
    "followed_at": "2018-01-01 12:00:00"
  }
]

您只需调用insertUsers方法，将所有通过from_id识别的用户数据插入到from_user中。

use romanzipp\Twitch\Twitch;

$twitch = new Twitch;

$result = $twitch->getUsersFollows(['to_id' => 654321]);

$result->insertUsers($twitch, 'from_id', 'from_user');

新的结果数据

[
  {
    "from_id": "123456",
    "to_id": "654321",
    "followed_at": "2018-01-01 12:00:00",
    "from_user": {
      "id": "123456",
      "display_name": "HerrAusragend",
      "login": "herrausragend"
    }
  }
]

定义EventSub处理器

默认情况下，EventSub webhook控制器将自动处理所有EventSub通知和撤销调用；但是，如果您有其他需要处理的webhook事件，可以通过扩展EventSub webhook控制器来实现。

为确保您的应用程序可以处理EventSub webhooks，请确保在传输有效负载中配置webhook回调URL。

您控制器的方法名称应与Laravel Twitch的控制器约定相匹配。具体来说，方法应以前缀handle开头，以Notification结尾，并使用您要处理的EventSub类型的“驼峰式”名称。例如，如果您想处理channel.follow类型，您应在控制器中添加一个handleChannelFollowNotification方法。

<?php

namespace App\Http\Controllers;

use romanzipp\Twitch\Http\Controllers\EventSubController as BaseController;
use Symfony\Component\HttpFoundation\Response;

class EventSubController extends BaseController
{
    public function handleChannelFollowNotification(array $payload): Response
    {
        return $this->successMethod(); // handle the channel follow notification...
    }

    protected function handleNotification(array $payload): Response
    {
        return $this->successMethod(); // handle all other incoming notifications...
    }

    protected function handleRevocation(array $payload): Response
    {
        return $this->successMethod(); // handle the subscription revocation...
    }
}

接下来，在您的应用程序的routes/api.php文件中定义一个路由到您的EventSub webhook控制器。

use App\Http\Controllers\EventSubController;

Route::post(
    'twitch/eventsub/webhook',
    [EventSubController::class, 'handleWebhook']
);

创建EventSub订阅

重要：在创建订阅时，您必须指定一个用于验证的密钥，如上“配置”部分所述。如果未显式定义，则此密钥将自动附加到webhook传输。

use romanzipp\Twitch\Enums\EventSubType;
use romanzipp\Twitch\Twitch;

$twitch = new Twitch;


$twitch->subscribeEventSub([], [
    'type' => EventSubType::STREAM_ONLINE,
    'version' => '1',
    'condition' => [
        'broadcaster_user_id' => '1337',
    ],
    'transport' => [
        'method' => 'webhook',
        'callback' => 'https://example.com/api/twitch/eventsub/webhook',
    ]
]);

事件订阅列表

use romanzipp\Twitch\Twitch;

$twitch = new Twitch;

$result = $twitch->getEventSubs(['status' => 'notification_failures_exceeded']);

foreach ($result->data() as $item) {
    // process the subscription
}

删除事件订阅

use romanzipp\Twitch\Twitch;

$twitch = new Twitch;

$twitch->unsubscribeEventSub([
    'id' => '932b34ad-821a-490f-af43-b327187d0f5c'
]);

Twitch扩展保护

1. 创建TwitchUserProvider

创建 app/Auth/TwitchUserProvider.php

namespace App\Auth;

use App\User;
use romanzipp\Twitch\Auth\TwitchUserProvider;
use Illuminate\Contracts\Auth\Authenticatable;
  
class TwitchUserProvider extends TwitchUserProvider  
{  
	public function retrieveById($identifier): ?Authenticatable  
	{
		/** @var User $user */  
		$user = User::query()->whereKey($identifier)->first();  

		return $user;  
	}  

    // This method is optional, if you don't want automatic user creation on request.
	public function createFromTwitchToken($decoded): ?Authenticatable  
	{
		return User::createFromTwitchToken($decoded);  
	}  
}

2. 注册TwitchUserProvider和TwitchExtensionGuard

编辑 app/Providers/AuthServiceProvider.php

use App\Auth\TwitchUserProvider;
use romanzipp\Twitch\Auth\TwitchExtensionGuard;
use romanzipp\Twitch\Auth\TwitchUserProvider;

public function boot()  
{  
	...
	
	$this->app->bind(TwitchUserProvider::class, Auth\TwitchUserProvider::class);
	TwitchExtensionGuard::register(config('twitch-api.ext_secret'));  
}

3. 在Laravel中使保护可用

编辑 config/auth.php

<?php

return [
    ...
    'guards' => [
        ...
        'twitch-extension' => [
            'driver' => 'laravel-twitch',
            'provider' => 'laravel-twitch',
        ],
    ],
    ...
];

文档

Twitch Helix API文档：https://dev.twitch.tv/docs/api/reference

分析

public function getExtensionAnalytics(array $parameters = [])
public function getGameAnalytics(array $parameters = [])

bits

public function getCheermotes(array $parameters = [])
public function getBitsLeaderboard(array $parameters = [])
public function getExtensionTransactions(array $parameters = [])

频道点数

public function createCustomRewards(array $parameters = [], array $body = [])
public function deleteCustomReward(array $parameters = [])
public function getCustomReward(array $parameters = [])
public function getCustomRewardRedemption(array $parameters = [], ?Paginator $paginator = NULL)
public function updateCustomReward(array $parameters = [], array $body = [])
public function updateRedemptionStatus(array $parameters = [], array $body = [])

频道

public function getChannels(array $parameters = [])
public function updateChannels(array $parameters = [], array $body = [])
public function getChannelEditors(array $parameters = [])
public function getChannelFollowers(array $parameters = [], ?Paginator $paginator = NULL)
public function getChannelsFollowed(array $parameters = [], ?Paginator $paginator = NULL)

慈善

public function getCharityCampaign(array $parameters = [])

聊天

public function getChannelChatEmotes(array $parameters = [])
public function getGlobalChatEmotes()
public function getChatEmoteSets(array $parameters = [])
public function getChannelChatBadges(array $parameters = [])
public function getGlobalChatBadges()
public function getChatSettings(array $parameters = [])
public function updateChatSettings(array $parameters, array $body = [])
public function sendChatAnnouncement(array $parameters = [], array $body = [])
public function getUserChatColor(array $parameters = [])
public function updateUserChatColor(array $parameters = [])
public function getChatters(array $parameters = [], ?Paginator $paginator = NULL)
public function sendShoutout(array $parameters = [])

剪辑

public function createClip(array $parameters = [])
public function getClips(array $parameters = [], ?Paginator $paginator = NULL)

权益

public function createEntitlementUrl(array $parameters = []) // DEPRECATED
public function getEntitlementsCodeStatus(array $parameters = [])
public function getDropsEntitlements(array $parameters = [])
public function redeemEntitlementsCode(array $parameters = [])
public function updateDropsEntitlements(array $parameters = [], array $body = [])

事件订阅

public function subscribeEventSub(array $parameters = [], array $body = [])
public function unsubscribeEventSub(array $parameters = [])
public function getEventSubs(array $parameters = [], ?Paginator $paginator = NULL)

扩展

public function getAuthedUserExtensions()
public function getAuthedUserActiveExtensions()
public function disableAllExtensions()
public function disableUserExtensionById(?string $parameter = NULL)
public function disableUserExtensionByName(?string $parameter = NULL)
public function updateUserExtensions(?string $method = NULL, ?string $parameter = NULL, bool $disabled = false)
public function getExtensionConfigurationSegment(array $parameters = [])
public function setExtensionConfigurationSegment(array $body = [])
public function setExtensionRequiredConfiguration(array $parameters = [], array $body = [])
public function sendExtensionPubSubMessage(array $body = [])
public function getExtensionLiveChannels(array $parameters = [], ?Paginator $paginator = NULL)
public function getExtensionSecrets(array $parameters = [])
public function createExtensionSecret(array $parameters = [])
public function sendExtensionChatMessage(array $parameters = [], array $body = [])
public function getExtensions(array $parameters = [])
public function getReleasedExtensions(array $parameters = [])
public function getExtensionBitsProducts(array $parameters = [])
public function updateExtensionBitsProduct(array $parameters = [], array $body = [])

游戏

public function getTopGames(array $parameters = [], ?Paginator $paginator = NULL)
public function getGames(array $parameters = [])

目标

public function getCreatorGoals(array $parameters = [])

激情列车

public function getHypeTrainEvents(array $parameters = [])

管理

public function checkAutoModStatus(array $parameters = [], array $body = [])
public function getBannedUsers(array $parameters = [], ?Paginator $paginator = NULL)
public function getBannedEvents(array $parameters = [], ?Paginator $paginator = NULL) // DEPRECATED
public function getModerators(array $parameters = [], ?Paginator $paginator = NULL)
public function getModeratorEvents(array $parameters = [], ?Paginator $paginator = NULL) // DEPRECATED
public function manageHeldAutoModMessages(array $parameters = [], array $body = [])
public function getAutoModSettings(array $parameters = [])
public function updateAutoModSettings(array $parameters = [], array $body = [])
public function banUser(array $parameters = [], array $body = [])
public function unbanUser(array $parameters = [])
public function getBlockedTerms(array $parameters = [], ?Paginator $paginator = NULL)
public function addBlockedTerm(array $parameters = [], array $body = [])
public function removeBlockedTerm(array $parameters = [])
public function deleteChatMessages(array $parameters = [])
public function addChannelModerator(array $parameters = [])
public function removeChannelModerator(array $parameters = [])
public function getVIPs(array $parameters = [], ?Paginator $paginator = NULL)
public function addChannelVIP(array $parameters = [])
public function removeChannelVIP(array $parameters = [])
public function getShieldModeStatus(array $parameters = [])
public function updateShieldModeStatus(array $parameters = [], array $body = [])

音乐

public function getSoundtrackCurrentTrack(array $parameters = [])
public function getSoundtrackPlaylist(array $parameters = [], ?Paginator $paginator = NULL)
public function getSoundtrackPlaylists(array $parameters = [])

OAuth

public function getOAuthAuthorizeUrl(string $responseType = 'code', array $scopes = [], ?string $state = NULL, bool $forceVerify = false)
public function getOAuthToken(?string $code = NULL, string $grantType = 'authorization_code', array $scopes = [])
public function validateOAuthToken()

投票

public function getPolls(array $parameters = [], ?Paginator $paginator = NULL)
public function createPoll(array $parameters = [], array $body = [])
public function endPoll(array $parameters = [], array $body = [])

预测

public function getPredictions(array $parameters = [], ?Paginator $paginator = NULL)
public function createPrediction(array $parameters = [], array $body = [])
public function endPrediction(array $parameters = [], array $body = [])

突袭

public function startRaid(array $parameters = [])
public function cancelRaid(array $parameters = [])

日程表

public function getChannelStreamSchedule(array $parameters = [], ?Paginator $paginator = NULL)
public function getChanneliCalendar(array $parameters = [])
public function updateChannelStreamSchedule(array $parameters = [])
public function createChannelStreamScheduleSegment(array $parameters = [], array $body = [])
public function updateChannelStreamScheduleSegment(array $parameters = [], array $body = [])
public function deleteChannelStreamScheduleSegment(array $parameters = [], array $body = [])

搜索

public function searchCategories(array $parameters = [])
public function searchChannels(array $parameters = [])

直播

public function getStreamKey(array $parameters = [])
public function getStreams(array $parameters = [], ?Paginator $paginator = NULL)
public function getFollowedStreams(array $parameters = [], ?Paginator $paginator = NULL)
public function createStreamMarker(array $parameters = [], array $body = [])
public function getStreamMarkers(array $parameters = [], ?Paginator $paginator = NULL)

团队

public function getChannelTeams(array $parameters = [])
public function getTeams(array $parameters = [])

用户

public function createUserFollows(array $parameters = [], array $body = [])
public function deleteUserFollows(array $parameters = [])
public function getUsers(array $parameters = [])
public function getUsersFollows(array $parameters = [], ?Paginator $paginator = NULL) // DEPRECATED
public function updateUser(array $parameters = [])
public function getUserExtensions(array $parameters = [])
public function getUserActiveExtensions(array $parameters = [])
public function updateUserExtension(array $parameters = [], array $body = [])
public function getUserBlockList(array $parameters = [], ?Paginator $paginator = NULL)
public function blockUser(array $parameters = [])
public function unblockUser(array $parameters = [])

视频

public function getVideos(array $parameters = [], ?Paginator $paginator = NULL)
public function deleteVideos(array $parameters = [])

Webhooks

public function getWebhookSubscriptions(array $parameters = []) // DEPRECATED
public function subscribeWebhook(array $parameters = [], array $body = []) // DEPRECATED
public function unsubscribeWebhook(array $parameters = [], array $body = []) // DEPRECATED
public function buildWebhookTopic(string $path, array $parameters = []) // DEPRECATED

低语

public function sendWhisper(array $parameters = [], array $body = [])

OAuth作用域枚举

升级

开发

运行测试

composer test

CLIENT_ID=xxxx composer test

CLIENT_ID=xxxx CLIENT_SECRET=xxxx composer test

生成文档

composer docs

加入Twitch Dev Discord！

romanzipp / laravel-twitch

维护者

详细信息