Twitch Client Bundle Laravel Package

Getting Started

This package is a Symfony-style bundle that wraps the Twitch Helix API client. In a Laravel app you will usually consume it as a plain Composer library rather than relying on bundle auto-registration.

1. composer require mrgoodbytes8667/twitch-client-bundle
2. Add credentials to .env: TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET (and a TWITCH_USER_TOKEN/refresh token if you need user-scoped endpoints — app access tokens only cover public data).
3. If you want container integration, write a small TwitchServiceProvider that binds the underlying client as a singleton, reading config from config/services.php. There is no Laravel package discovery here, so nothing is wired for you.
4. First use case: resolve a user by login and check whether they are live.

$client = app(\Twitch\Client::class);
$user   = $client->users()->get(['login' => 'twitchdev']);
$stream = $client->streams()->get(['user_login' => 'twitchdev']);

Where to look first: the bundle's DependencyInjection/Configuration.php for the config tree (that is the authoritative list of options), the service aliases in Resources/config/services.*, and the README's quickstart. Read those three before touching the API wrapper — the config keys are not always mirrored in the docs.

Implementation Patterns

Singleton client + thin repository wrappers. Bind the client once, then wrap each resource family (users(), streams(), videos(), clips()) in your own small class so your app code does not speak the vendor's fluent API. When the package bumps a major 0.x version, only the wrappers need to change.

Two token strategies. Use an app access token (client credentials) for public read endpoints and keep it in the cache for its ~60-day lifetime. Use a user token only for endpoints that require scopes (channel points, subscriptions you own, moderator actions). Store the refresh token encrypted and refresh on 401, not on a timer.

Cache aggressively; the rate limit is per client ID. Helix enforces a points-per-minute bucket (roughly 800 points as of the current API). Wrap read calls in Cache::remember() with short TTLs (30–60s for live status, minutes-to-hours for user/video metadata) and read Ratelimit-Remaining / Ratelimit-Reset off the response if you need adaptive backoff.

Pagination belongs in a job. Endpoints returning cursors (followers, videos, clips) should be iterated inside a queued job with $client->...(..., ['after' => $cursor]), dispatching follow-up jobs rather than looping in a request. Twitch endpoints are slow enough that a 5-page loop will blow a web request timeout.

EventSub over polling where possible. For "is this streamer live", EventSub webhooks are cheaper than polling streams(). Register the subscription with the client, expose a Laravel route as the callback, and verify the Twitch-Eventsub-Message-Signature HMAC (sha256 of message ID + timestamp + raw body, keyed by your webhook secret) before parsing JSON. Respond 2xx fast and push the work to a queue.

Testing. Point the underlying HTTP client at a Guzzle MockHandler and assert on the request URIs. Keep a small fixture set of Helix JSON responses; the shape of data/pagination is stable enough that fixtures survive upgrades.

Gotchas and Tips

v0.7.5 restores the deprecated functions that were removed in v0.7.3/v0.7.4. PR #23 deleted a set of deprecated methods; v0.7.5 reverts that. Practical consequences:

• If you upgraded to 0.7.3/0.7.4 and patched your code to stop calling those methods, nothing breaks on 0.7.5 — your replacements still work, and the old methods simply reappear.
• If you were pinned to 0.7.2 and could not upgrade because removal broke you, 0.7.5 is the safe target.
• Do not start using the restored methods in new code. They were deprecated for a reason and the revert was a compatibility concession, not a design decision. Expect them to be removed again in a future release, likely a 0.8.0.
• If you run with deprecation notices promoted to exceptions (common with symfony/phpunit-bridge or strict error handlers), check whether the restored methods trigger trigger_deprecation() on call — that will surface in test runs but not production.

Treat 0.x as unstable. This is a pre-1.0 package; ^0.7 is unsafe because it permits breaking changes across minor bumps, and the #23 → #41 revert is a live demonstration of that. Pin to ~0.7.5 or an exact version and upgrade deliberately.

There is no Laravel auto-discovery. If you assumed the bundle would register itself, you will get "target class does not exist" on the container bind. Register the provider manually or resolve the client directly.

Config keys differ from the README in places. The extension alias (e.g. twitch_client:) is the root for bundle config; in Laravel you are supplying an array to the client constructor/factory instead, so translate names rather than copy-pasting YAML.

Client-ID is mandatory on every request, including ones you think are token-only. A missing header returns 401 with a body that looks like an auth failure, which sends people chasing token bugs for an hour.

Token expiry is silent. The client generally does not auto-refresh unless you wire it. Catch 401, refresh once, retry once, and guard against refresh storms with a cache lock — concurrent queue workers will otherwise all refresh simultaneously.

Extension points. Decorate the client service rather than forking: push a Guzzle middleware for logging, retry-on-5xx, and metric collection. For anything the bundle does not model (new Helix endpoints land faster than 0.7.x releases), fall back to the raw HTTP client for that one call rather than waiting on a package bump.