Oauth2 Github Laravel Package

Product Decisions This Supports

• "Sign in with GitHub" as an activation lever. Developer-facing products live and die on time-to-first-value; an OAuth handshake is the gate between a signup form and a working integration. This package is the token-exchange half of that flow, so it directly unblocks the onboarding funnel for any dev-tool, CI, or repo-analytics feature.
• Build vs. buy for the OAuth dance. The decision isn't "GitHub OAuth, yes/no" — it's "do we hand-roll state/PKCE/callback validation, or adopt a provider library?" Adopting a thin, MIT-licensed provider shifts ~200 lines of security-sensitive code out of your codebase and onto a known-good implementation of RFC 6749. That is almost always the cheaper, safer call.
• Roadmap: integration surface area. GitHub OAuth is the wedge for a larger dev-tooling roadmap — repo metadata, PR status checks, org-membership gating, webhook-driven automation. Approving this package now means the next features (org-scoped access, private repo reads) reuse the same token plumbing instead of re-litigating auth.
• Architecture: provider abstraction. Sitting on top of league/oauth2-client means GitHub is one class among many; adding GitLab or Bitbucket later is a provider swap, not a rewrite. That's a real option value when your ICP is "engineering teams" and the second-integration request arrives six months in.
• Access-control decisions. GitHub OAuth scopes (read:org, repo) let you gate features on real org membership rather than an email-domain heuristic — a materially better enterprise-sales story ("you can only see your team's data") and a cheaper one than building SAML.
• Explicit non-decision: GitHub Apps. If the roadmap includes installation-based permissions, webhooks, or bot identities, OAuth Apps are the wrong primitive and this package is the wrong tool. Deciding that early is itself a roadmap call this assessment forces.
• Runtime-floor decision (new in 2.0.0). The 2.0.0 major bump drops PHP 5.5 and adds PHP 7.1 support. Anyone still running PHP 5.5/5.6 or 7.0 must pin to 1.x or upgrade their runtime — a fleet-modernization question, not just a dependency question. For a modern codebase this is a non-event; it only matters if any service in scope is on an EOL PHP.

When to Consider This Package

Adopt when:

• You are already standardized on league/oauth2-client and need a GitHub provider for a non-Laravel PHP service.
• You want direct control over the OAuth flow — custom scopes, refresh-token handling, state/PKCE configuration, or a bespoke callback flow that Socialite's opinionated driver doesn't expose.
• You are building a provider-agnostic integration layer and want GitHub to plug into the same interface as other identity providers.
• Your runtime is PHP 7.1+ (required as of 2.0.0).
• Your need is genuinely "login + read a user's basic profile" and nothing more.

Look elsewhere when:

• Laravel app + standard social login → use Socialite. Laravel ships a first-party GitHub driver. Adding this package is a redundant dependency and a second mental model for the same flow. This is the most common false positive for this package.
• GitHub App / installation tokens / webhook verification → use a GitHub App-capable client (knplabs/github-api, Octokit equivalents). OAuth2 user tokens are a different permission model.
• Device flow (CLI login) → not supported here; you need the device-authorization grant.
• GitHub Enterprise Server → verify base-URL overrides end-to-end before committing; don't assume.
• You need an SLAs or a security-response cadence. Maintenance has ticked over — 2.0.0 (PHP 7.1 support, PHP 5.5 removal) is the first release since January 2017 — but a single housekeeping release is a sign of life, not a support contract. There is still no stated deprecation policy, no CVE process, and no evidence that PHP 8.x / PKCE behavior has been validated. Confirm in a spike rather than taking it on faith.
• You cannot move off PHP < 7.1. 2.0.0 is a breaking change by runtime floor; pin to 1.x (unmaintained) or upgrade.

Mitigation if you adopt anyway: wrap it behind your own GitHubAuth interface, vendor or fork if needed, pin the version (^2.0), and log it in the tech-debt register with a named fallback (GenericProvider with GitHub endpoints configured manually is a ~20-line escape hatch). Treat it as a 2-file convenience, not a strategic dependency. Note that the 2.0.0 bump is a removal, not a feature release — the integration code you write against it is the same as 1.x, so the migration cost for existing consumers is a runtime check, not a rewrite.

How to Pitch It (Stakeholders)

For executives — one paragraph: This is a small, free, MIT-licensed component that lets the product offer "Sign in with GitHub" without our engineers building the security-sensitive token exchange from scratch. It is not a platform bet — it's roughly two classes of glue code with no lock-in, replaceable in an afternoon. The strategic value is speed: it shortens the path from signup to a working GitHub integration, which is our fastest route into developer teams and the prerequisite for a much larger repo-and-automation roadmap. On the risk side, the maintenance picture improved slightly with the 2.0.0 release — the package now supports PHP 7.1 and the project shipped its first update since 2017 — though one housekeeping release is a sign of life, not a support guarantee. Because the code surface is tiny and sits on a well-maintained foundation, we treat the residual risk as manageable: we isolate it behind our own interface and can swap it out cheaply.

For engineering — the ask: Adopt league/oauth2-github ^2.0 behind an internal auth interface for [service], not scattered through controllers. Confirm your target runtime is PHP 7.1+ — 2.0.0 drops PHP 5.5 and is a breaking change on the runtime floor, so any PHP 5.6/7.0 service must either upgrade or pin to 1.x. The 2.0.0 notes contain no API, scope, or security changes, so integration code is unchanged from 1.x; the migration is a runtime check, not a rewrite. Timebox a half-day spike to confirm PHP 8.x compatibility, PKCE behavior, and Enterprise base-URL override — 2.0.0 added PHP 7.1 support, which does not establish PHP 8.x readiness. If the spike fails, fall back to GenericProvider with manually configured GitHub endpoints — same foundation, no external dependency. Do not add it to the Laravel app, which should use Socialite's built-in driver. Do not use it if we're heading toward GitHub Apps.

Bottom line: Low cost, low ceiling, real but bounded risk — and slightly less bounded than it was, given the first maintenance activity in years. The 2.0.0 release is a PHP-floor bump, not a capability upgrade; it changes the go/no-go only for services still on PHP 5.5–7.0. Worth it for a single well-scoped GitHub login requirement; not worth it as a foundation for a GitHub integration platform.