classicvalues / twitch-api-php

A Twitch API client for PHP.

twitch-api-php

New Twitch API (Helix)

A New Twitch API (Helix) client for PHP. The code for the new API is all contained within src/NewApi/. This is because the New API code is meant to be separate from the old Kraken API code, such that in the future, when Kraken is no longer available, the old Kraken code can be removed without affecting the new API code. Additionally, keeping them separate allows for existing code using the Kraken part of this library to continue to function, untouched by the new code.

The New Twitch API client is still being developed and is currently incomplete. The endpoints that are implemented are usable, but not all endpoints have been implemented yet. If an endpoint you need is missing, incomplete, or not working correctly, please report it or fix it if you can and create a PR for it.

Usage

Everything stems from the NewTwitchApi class. However, if you want to individually instantiate UsersApi, OauthApi, etc. you are free to do so.

The API calls generally return an object implementing ResponseInterface. Since you are getting the full Response object, you'll need to handle its contents, e.g. by decoding then into an object with json_decode(). This library does not assume this is what you want to do, so it does not do this for you automatically. This library simply acts as a middleman between your code and Twitch, providing you with the raw responses the Twitch API returns.

The individual API classes that can be called from NewTwitchApi correspond to the New Twitch API documentation. OauthApi is for Oauth calls. WebhooksSubscriptionApi is for subscribing/unsubscribing to webhooks. The rest of the API classes are based on the resources listed here. The methods in the classes generally correspond to the endpoints for each resource. The naming convention was chosen to try and match the Twitch documentation. Each primary endpoint method (not convenience or helper methods) should have an @link annotation with a URL to that endpoint's specific documentation.

Examples

Getting a user's information via their access token:

// Assuming you already have the access token.
$accessToken = 'the token';

// The Guzzle client used can be the included `HelixGuzzleClient` class, for convenience. 
// You can also use a mock, fake, or other double for testing, of course.
$helixGuzzleClient = new HelixGuzzleClient();

// Instantiate NewTwitchApi. Can be done in a service layer and injected as well.
$newTwitchApi = new NewTwitchApi($helixGuzzleClient, $clientId, $clientSecret);

try {
    // Make the API call. A ResponseInterface object is returned.
    $response = $newTwitchApi->getUsersApi()->getUserByAccessToken($accessToken);
} (catch GuzzleException $e) {
    // Handle error appropriately for your application
}

// Get and decode the actual content sent by Twitch.
$responseContent = json_decode($response->getBody()->getContents());

// Return the first (or only) user.
return $responseContent->data[0];

CLI Test Client

In order to make testing the New Twitch API code easier, there is an interactive CLI script that can be run. This is found at bin/new-api-cli-test-client.php.

To run it, execute ./bin/new-api-cli-test-client.php <client-id> <client-secret>, passing in your client ID and secret, respectively. The script will interactively walk you through the rest. You'll be prompted for which API endpoint you'd like to call. Then, you'll be prompted for any parameters that are available for that call. After the API call is made, you're presented with the URI of the request followed by the body of the response.

Here's an example of the CLI client in action, getting the game information for Minecraft and then validating an invalid access token.

$ ./bin/new-api-cli-test-client.php REDACTED_CLIENT_ID REDACTED_CLIENT_SECRET
Twitch API Testing Tool

Which endpoint would you like to call?
0) Quit
1) Validate an Access Token
2) Refresh an Access Token
3) Get Games
4) Get Streams
5) Get Users
6) Get Users Follows
Choice: 3

Get Games
IDs (separated by commas):
Names (separated by commas): Minecraft

games?name=Minecraft

{
    "data": [
        {
            "id": "27471",
            "name": "Minecraft",
            "box_art_url": "https:\/\/static-cdn.jtvnw.net\/ttv-boxart\/Minecraft-{width}x{height}.jpg"
        }
    ]
}

Which endpoint would you like to call?
0) Quit
1) Validate an Access Token
2) Refresh an Access Token
3) Get Games
4) Get Streams
5) Get Users
6) Get Users Follows
Choice: 1

Validate an Access Token
Access token: foobar

/oauth2/validate

{
    "status": 401,
    "message": "invalid access token"
}

Which endpoint would you like to call?
0) Quit
1) Validate an Access Token
2) Refresh an Access Token
3) Get Games
4) Get Streams
5) Get Users
6) Get Users Follows
Choice: 0

Quit
$

Developer Tools

PHP Coding Standards Fixer

PHP Coding Standards Fixer (php-cs-fixer) has been added, specifically for the New Twitch API code. A configuration file for it can be found in .php_cs.dist. The ruleset is left at default (PSR-2 at this time). The configuration file mostly just limits it's scope to only the New Twitch API code.

You can run the fixer with vendor/bin/php-cs-fixer fix. However, the easiest way to run the fixer is with the provided git hook.

Git pre-commit Hook

In bin/git/hooks, you'll find a pre-commit hook that you can add to git that will automatically run the php-cs-fixer everytime you commit. The result is that, after the commit is made, any changes that fixer has made are left as unstaged changes. You can review them, then add and commit them.

To install the hook, go to .git/hooks and ln -s ../../bin/git/hooks/pre-commit.

API Documentation

The New Twitch API docs can be found here.

License

Distributed under the MIT license.

---

---

---

Kraken

A Twitch Kraken API client for PHP. This is the old API, which is deprecated and will be deleted soon. Please use Helix instead. If something is missing from the Helix API, please add it or request it.

The documentation below is left for legacy purposes, until Kraken support is removed.

Supported APIs

This library aims to support v3 and v5 of the Twitch API until each one becomes deprecated. If an API version is not specified, v5 will be used as the default.

Features Completed

Main API Endpoints:

• Authentication
• Bits
• Channel Feed
• Channels
• Chat
• Clips
• Collections
• Communities
• Games
• Ingests
• Search
• Streams
• Teams
• Users
• Videos

Any endpoints missing? Open an issue here.

Basic Example

$options = [
    'client_id' => 'YOUR-CLIENT-ID',
];

$twitchApi = new \TwitchApi\TwitchApi($options);
$user = $twitchApi->getUser(26490481);

// By default API responses are returned as an array, but if you want the raw JSON instead:
$twitchApi->setReturnJson(true);
$user = $twitchApi->getUser(26490481);

// If you want to switch between API versions on the fly:
$twitchApi->setApiVersion(3);
$user = $twitchApi->getUser('summit1g');

See the examples directory for more common use cases.

Requirements

PHP 5.6 or higher is required.

Installation

Either pull in the library via composer:

composer require nicklaw5/twitch-api-php

or add the following dependency to your composer.json file and run composer install:

"nicklaw5/twitch-api-php": "~1.0"

Tests

All unit tests can be run with the following command:

vendor/bin/phpunit # or simply "phpunit" if you have it installed globally

Documentation

The Twitch API docs can be found here.

As for the documentation of this library, that is still on the to-do list. In the meantime, most modern IDEs by default, or through the use of plugins, will provide class property and method auto-completion. Or you can simple look through the source code.

License

Distributed under the MIT license.