omnishow / twitch

1.x-dev 2026-11-10 06:42 UTC

Requires

• php: >=8.2
• omnisense/contracts: ^1.0@dev
• omnisense/omnishow: ^1.0@dev
• symfony/http-client: ^6.4|^7.0|^8.0

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.0

MIT

• Marco Meyer

• stream
• schedule
• live
• twitch
• framework-agnostic
• helix
• omnishow

Published on Packagist.org on 2026-11-10 08:18 UTC

README

omnisense/omnishow's Twitch, under any PHP host, through the Helix API with an app access token. It implements the live contract:

• whether a channel is live and its stream (GET /streams?user_login=): title, category, viewers, start, language, thumbnail, its page and its player;
• its schedule (GET /users?login= for its id, then GET /schedule?broadcaster_id=), soonest first, a cancelled segment said (LiveState::Cancelled), a weekly one marked recurring.

use Omnishow\Twitch\TwitchFactory;

$twitch = (new TwitchFactory($httpClient))->create(['client_id' => getenv('TWITCH_CLIENT_ID'), 'client_secret' => getenv('TWITCH_CLIENT_SECRET')]);
$now = $twitch->live('twitchdev');                 // null when off air
echo $now?->embed(parent: 'example.org');         // https://player.twitch.tv/?channel=twitchdev&parent=example.org
$next = $twitch->schedule('twitchdev', 5);

A channel is named by its login (twitch.tv/<login>; an address or a leading @ are read too). Twitch's player needs the embedding page's domain (parent=), and has no privacy-friendly variant.

Options: client_id (required), and client_secret (an app access token is asked with it, POST https://id.twitch.tv/oauth2/token, and asked again a minute before it expires) or token (an access token got elsewhere, sent as it is); api (https://api.twitch.tv/helix/), token_url. See docs/index.md.

Usage policy

The package declares Twitch's usage policy as data, in policy.json (omnisense/contracts' schema, read at its sources on 2026-11-10): rate limits Helix's points bucket, refilled every minute, whose size is not stated as policy: unknown (a site that knows its bucket declares it in points, {"max": 800, "window": "minute", "unit": "points", "cost": {"schedule": 2}}: schedule makes two requests); Ratelimit-Remaining and Ratelimit-Reset (a Unix time) read on every answer, an empty bucket holding every call until its reset; Twitch content cached 24 hours at most, no re-syndication nor redistribution, no selling or monetizing its data without an agreement, a clear path to the source from every display. Through omnishow's registry every call is held to it: a site's own limit is counted; a 429 holds every call until its wait is over, a 429 and its Retry-After hold every next call until the wait is over (UsageLimitReachedException), and a site may tighten the policy in its configuration ('policy' => [...]), never loosen it. What the terms do not say is declared unknown; the sources and the details are in the file's provenance.

Responsibility

This package is an independent, unofficial client: it is not affiliated with, endorsed by or sponsored by Twitch Interactive, Inc. It reaches their service on behalf of whoever runs it, and it does not redistribute their data beyond the short excerpts written by hand as test fixtures. Its MIT licence covers this package's code only and grants no right to the service or to its data.

Whoever installs and runs this package is responsible for complying with Twitch's terms (Developer Services Agreement, Terms of Service), for obtaining whatever they require (an application, its client id and secret, a rate limit to respect), and for any use made of what it returns. The authors publish it free of charge, make no commercial use of it, and accept no liability for how it is used (see LICENSE).

Licence

MIT.