Qq Laravel Package

Technical Evaluation

What the package actually is. A thin, read-only subtree split of a single provider inside the SocialiteProviders/Providers monorepo. It contributes one driver class and one listener that teaches laravel/socialite how to speak Tencent QQ's OAuth 2.0 dialect. The entire functional surface is roughly 100–150 lines. This is not architecture; it is a protocol adapter.

Architecture fit. Fits cleanly if and only if the host application is Laravel and already uses Socialite for other identity providers. It registers through the SocialiteWasCalled event and slots into the existing Socialite::driver('qq') contract, which means it inherits Socialite's state/CSRF handling, redirect flow, and User abstraction for free. There is no new infrastructure, no persistence, no service to operate. If the app is Symfony, Slim, or a non-Laravel PHP stack, the package is unusable — Socialite is Laravel-coupled — and the correct move is league/oauth2-client with a hand-written QQ provider.

Integration feasibility. The code is trivial; the constraints are not. Three items dominate:

• Dependency freshness. Last release 2022-07-25. Socialite and the socialiteproviders/manager shim have both moved since (Laravel 10, 11, 12; PHP 8.3/8.4). The split repo's tags are generated from the upstream monorepo, so a three-year gap plausibly means the illuminate/support constraint is pinned to ^6|^7|^8|^9 and will not resolve on a modern Laravel app without --with-all-dependencies gymnastics or a fork. This must be verified by a spike, not by reading the README.
• QQ's non-standard protocol. The token endpoint returns a URL-encoded body rather than JSON; identity comes from graph.qq.com/oauth2.0/me, which returns a JSONP-wrapped payload (callback( {...} );) containing openid; profile data requires a second call to user/get_user_info with oauth_consumer_key and openid as query parameters. The provider absorbs all of this — which is precisely the value it delivers — but it also means any bug in that parsing is a bug you cannot patch in place (see Operational Impact).
• No email claim. QQ returns nickname, avatar, gender, province, city, year — never an email address. Email-based account matching, deduplication, and password recovery are all off the table. Your identity model must key on openid (app-scoped) and ideally unionid (developer-account-scoped, stable across apps).

Technical risk.

Key questions to answer before committing.

1. Does composer require socialiteproviders/qq resolve cleanly against our current Laravel and PHP versions? If not, is upstream main usable, or is a fork required?
2. Do we have (or can we obtain) a QQ互联 developer account, a Chinese business entity, and an ICP-filed callback domain? Who owns that relationship?
3. Is QQ login a genuine acquisition requirement (mainland, gaming/younger-demographic skew) or a checkbox? WeChat is the larger prize in the same market and has better provider support.
4. Do we need unionid? If we may ever run more than one app or tenant, yes — enable it at registration time.
5. What is our account-linking policy for a provider that supplies no email?

Integration Approach

Stack fit. Accept only for Laravel 9+ applications already running Socialite. Reject for non-Laravel PHP; write the provider yourself in that case — it is a day of work.

Build vs. buy. Given the size of the artifact, treat buy as a convenience, not a commitment. The realistic decision tree:

• Constraint resolves and upstream is alive → adopt the package, pin the version, move on.
• Constraint conflicts or upstream is dormant → fork into our own namespace (or vendor a local path copy), keep the same class shape, and own ~150 lines. Do not use composer-patches for this; a fork is cleaner and lets us widen constraints ourselves.
• Either way, budget half a day to read the driver and the QQ endpoint contract. The failure modes are all in the protocol, not the PHP.

Migration path. Greenfield: add the package, register the listener (note Laravel 11+ has no default EventServiceProvider — wire Event::listen(SocialiteWasCalled::class, …) in AppServiceProvider), add a qq block in config/services.php, add routes, ship behind a feature flag. Brownfield: no migration is required — it is additive and does not touch existing providers. The only shared surface is the users table, which should not be modified; introduce a separate social_identities table (provider, provider_user_id = openid, unionid, raw JSON, linked_at) so that adding or dropping a provider never touches core user rows.

Compatibility checklist. socialiteproviders/manager major version, illuminate/support constraint, laravel/socialite major version, PHP version, and whether the listener registration style matches (the v3 SocialiteWasCalled event vs. older registration). Confirm on a throwaway app, not in the main repo.

Sequencing.

1. Day 0 — start the QQ互联 registration in parallel. This is the true critical path; it is a business/legal process, not an engineering one. Do not let it surface in week three.
2. Day 1 — feasibility spike. Throwaway Laravel app on our exact versions; composer require; drive a real login with a test QQ account (QQ互联 allows a small whitelist of test users). Measure latency from our deployment region.
3. Day 2 — decision record. Adopt / fork / build. Record the constraint result and the fork owner if applicable.
4. Week 1 — data model and wiring. social_identities migration, controller, state handling (session-backed for web; ->stateless() only if an SPA/API flow genuinely requires it, and only with a separately validated CSRF strategy), error routes, feature flag with a kill switch.
5. Week 2 — account linking and observability. Login-then-link UX for existing email users; structured logging of ret/msg, endpoint latency, and failure reason; alerting on failure-rate spikes.
6. Week 3 — staged rollout. Enable for a small cohort, watch the metrics, then widen.

Operational Impact

Maintenance. The package itself is near-zero maintenance when healthy — Socialite handles the moving parts. The ongoing cost is (a) tracking upstream for a release that widens framework constraints, and (b) monitoring QQ's endpoint behavior, which changes without notice and without a changelog. Because the repo is a read-only split, you cannot merge a fix into it: issues and PRs live in the monorepo, and a bug that matters to you may sit unfixed indefinitely with 49 stars of community pressure behind it. Plan for ownership: assign a named maintainer and decide up front whether that person can fork rather than wait.

Support. First-line support burden is modest but concentrated in one place: "QQ login didn't work" is almost never a code bug. It is a rejected redirect_uri (must match the registered domain exactly; wildcards are typically refused), a suspended or un-reviewed QQ app, a user who denied consent, or a network failure between your region and Tencent. Build a support runbook that maps symptoms to those causes, and surface the QQ ret code in your error page or logs so support can classify without engineering.

Scaling. The OAuth handshake is per-login and stateless on your side, so it scales with your web tier; there is no shared resource to saturate. The real capacity concerns are external: Graph API QPS limits, and the fact that each login costs two sequential round trips to Tencent. From servers outside mainland China, budget 400–1500 ms and set aggressive timeouts with a single retry for the token exchange only — never retry the profile fetch blindly if you have already established a session. Mirror avatars to your own storage rather than hotlinking qlogo.cn, both for latency and for longevity.

Failure modes to instrument.

• Token exchange returns an error string instead of a token (HTTP 200, error in body).
• Graph API returns ret != 0 with HTTP 200 — the single most likely thing to be missed by generic HTTP health checks.
• openid present but unionid absent because it was never enabled at registration.
• Access token expiry (long-lived, but refresh tokens rotate) on any flow that stores tokens for later profile refresh — better to not store tokens at all unless a feature needs them, and encrypt them if you do.
• state mismatch or replay on session-backed flows; explicit handling for users who land on the callback with an expired session.
• Tencent-side outage or app suspension: the login button must disappear or degrade gracefully via feature flag, not 500 the login page.
• Callback reached with code absent because the user denied consent — a normal path, not an error.

Ramp-up. For an engineer who already knows Socialite, half a day to read the driver and a day to wire and test. For an engineer who does not, add a day for Socialite's event registration and User contract. The genuinely long pole is organizational, not technical: QQ互联 registration and review, business-entity documentation, and ICP filing can consume one to three weeks and are entirely outside the team's control. Staff accordingly, and treat the 0.635 score as a fair signal — the code is fine, but the package is stale, thinly adopted, and gated behind a market-entry process that no amount of engineering effort can shortcut.