Sauth Bundle Laravel Package

Getting Started

0.2 is a non-breaking, additive release: GitHub joins whatever provider set the package already shipped with. Nothing is deprecated and there is no upgrade path to run, so the work is onboarding the new driver rather than migrating.

Start here, in this order:

1. Read the changelog and diff, not the release title. "Added Github support" is the headline; the detail that matters is how the driver was wired in (manager extend(), a tagged container binding, or a config-keyed map). That shape tells you whether adding Bitbucket/Gitea later is a one-liner or a fork.
2. Publish and diff the config. php artisan vendor:publish --tag=<package>-config then compare against the vendor copy — 0.2 almost certainly added a github block with a token, base URL (for Enterprise), and webhook secret. Copy only the new keys into your existing config rather than overwriting.
3. Inspect the driver directory. Look for the GitHub class and its siblings. If GitHub has methods the others don't, the package is only partially abstracted and you should design around that now.

Minimal first use — authenticate with a token and make one read call through the package's manager, not raw Http:::

composer require vendor/package:^0.2

// .env
GITHUB_TOKEN=ghp_xxx
GITHUB_BASE_URL=https://api.github.com   # override for GH Enterprise

$client = Package::driver('github');   // or config(['package.default' => 'github'])
$repos  = $client->repos()->all(['per_page' => 100]);

Good first real use case: post a deploy notification or open an issue from a queued job. It exercises auth, serialization, and error handling without touching write-heavy flows.

Implementation Patterns

Select the driver per call, not globally. Keep GitLab/GitHub side by side in one app:

$client = Package::driver($repo->provider); // 'github' | 'gitlab' ...

Never store user tokens in config. config() is cached at deploy time; per-user PATs and GitHub App installation tokens must be resolved at runtime from the DB or a secret store, then passed to the driver explicitly.

Wrap it in a thin adapter. Expose interface RepositoryGateway { public function openIssue(...): Issue; } and implement it over the package. The package is at 0.x — this is your insurance against a rename in 0.3.

Handle webhooks as a first-class path. Verify the signature in middleware, queue immediately, acknowledge with 202, then process:

Route::post('/webhooks/github', GithubWebhookController::class)
    ->middleware(['package.webhook:github']);  // verify HMAC on raw body

Deduplicate on X-GitHub-Delivery (a unique key on a webhook_events table) — GitHub retries aggressively and redelivers on timeout.

Test against fakes, not the network. Http::preventStrayRequests() in the base TestCase plus fixture payloads from real GitHub responses. For package-level work use Orchestra Testbench; for app-level work assert Http::assertSent(fn ($r) => $r->url() === '...').

Pin tightly. "vendor/package": "~0.2.0" — pre-1.0 semver permits breaking changes in a minor bump, and 0.x packages routinely ship them.

Gotchas and Tips

Token type confusion. Classic PATs use coarse scopes (repo, workflow); fine-grained PATs are per-repository with explicit permissions and a mandatory expiry. The package won't validate scopes for you — a 403 with a X-Accepted-GitHub-Permissions header means your token is under-scoped, not that the request is malformed. Handle 401 by invalidating the cached token, not by retrying.

Rate limits are two-dimensional. GitHub enforces primary limits (5000/hr authenticated) and secondary limits on burst concurrency. Honour Retry-After and X-RateLimit-Reset; on secondary limits the reset header can be absent. Use conditional requests (If-None-Match with a cached ETag) — a 304 does not count against your limit, which is the single biggest win for polling jobs.

Pagination lies. Use the Link header's rel="next", never page++ until empty and never a computed page count. per_page caps at 100, and GitHub Enterprise may cap lower.

Webhook signatures need the raw body. If any middleware touches the request body before verification, hash_equals fails silently. Verify before $request->all(), and use hash_equals, not ===.

Config cache bites in production only. config(['package.default' => 'github']) at runtime is fine; editing the config file on a server with a cached config is not. Deploy-time config:cache is the usual culprit behind "works locally".

Extension point check. If you want a provider the package doesn't ship, find whether Package::extend('name', fn () => ...) exists on the manager. If not, you're subclassing the driver base class — note the method signatures you depend on, since 0.x won't protect them.

Debugging. Http::globalRequestMiddleware(fn ($r) => logger()->debug((string) $r->url())) gives you the whole request log without Telescope; pair with -vvv on artisan commands. Redact Authorization and never dump() a request with a token in it.

Treat GitHub as the new kid. It's the youngest driver in the codebase and 0.2's release notes are one line — expect rougher edges than the established providers. Exercise the specific methods you need (issues, pulls, checks, statuses vary in support) before designing around them, and file upstream issues with the raw request/response rather than a summary.