Wechat Web Laravel Package

Technical Evaluation

Architecture fit. socialiteproviders/wechat-web is a Laravel Socialite driver, not a standalone SDK. It slots into an existing Socialite auth flow as one additional driver: one Composer package, one entry in config/services.php (client ID/secret/redirect), one SocialiteWasCalled listener registration, and a controller using Socialite::driver(...)->user(). It returns a Socialite-compatible User object and persists nothing — account mapping, session creation, and storage remain ours. That is a clean, low-coupling fit if Socialite is already the auth substrate. If it isn't, we are adopting Socialite plus socialiteproviders/manager to get one button.

The underlying flow is the WeChat Open Platform 网站应用 (website app) authorization-code flow with QR-code login: an outbound redirect to open.weixin.qq.com/connect/qrconnect, a callback carrying code, then server-side token and userinfo calls. Stateless, no webhooks, no daemons, no data residency surface beyond what we choose to store.

Integration feasibility. Engineering effort is genuinely small — roughly 1–2 days for a working, tested flow. The friction sits on both sides of the code:

• Upstream (business, not technical): a 网站应用 AppID requires a verified WeChat Open Platform account, a Chinese business licence, and an annual certification fee (~¥300). The callback domain must be ICP-filed. This is 2–6 weeks of calendar time if we don't already hold the credential — far longer than the code.
• Downstream (dependency, technical): last release 2020-12-01, i.e. Laravel 8-era. Declared illuminate/support and socialiteproviders/manager constraints almost certainly exclude Laravel 9/10/11 and PHP 8.1+. Expect composer require to fail on a modern app.

Technical risk.

Key questions.

1. Which Laravel and PHP versions must we support — and is an internal fork acceptable as the price of entry?
2. Do we already hold a 网站应用 AppID with QR-login permission, on an ICP-filed callback domain?
3. Is WeChat one login button, or one of several (公众号, mini-program, payments)? If several, the calculus changes entirely.
4. Do we need unionid for cross-channel account linking?
5. Who owns patching this when Laravel 12 ships? If the answer is "nobody," pick a different path now.
6. What is the fallback for users who abandon the QR scan or fail certification?

Integration Approach

Stack fit. Strong on Laravel 8 / PHP 7.3–8.0, which is the package's tested envelope. Below that, treat declared compatibility as unknown and prove it in a spike before committing.

Build vs. buy — four options, in preference order:

Migration path. No data migration is required by the package itself, but design for multi-channel identity from day one: a social_identities table (user_id, provider, provider_user_id, unionid nullable, unique on (provider, provider_user_id) and on unionid) rather than nullable columns on users. Keep password/phone login as a first-class fallback and add an explicit account-linking step for existing users, so a WeChat login never silently creates a duplicate account.

Compatibility and sequencing.

1. Confirm Open Platform AppID, QR-login permission, and ICP-filed callback domain.
2. Timeboxed spike: branch, target Laravel version, attempt install, measure breakage. Decision point on A/B/C.
3. Implement identity schema and linking rules (including the unionid-absent case).
4. Build the callback: state validation (Socialite default), explicit errcode handling, user-facing error states for scan-abandonment and expired codes, structured logging keyed on errcode.
5. Staging test with real scans on desktop Chrome/Safari plus a mobile browser outside WeChat.
6. Ship behind a feature flag; instrument button impression → QR render → successful login conversion, and watch the 40029/40163 rates.

Operational Impact

Maintenance. Effectively self-maintained: no release since 2020, community-only support routed to a monorepo we don't control. Budget ~2–4 engineer-days per year plus a patch at each Laravel major — and note that under option A that maintenance is ours by design, with the compensation of a smaller, fully understood surface.

Support. No vendor SLA. WeChat-side escalations go to Open Platform 客服: Chinese-language, business-hours, requires a verified account, and slow on domain/certification issues. Write an internal runbook covering credential rotation, callback-URL changes, and the "all logins failing" triage path.

Scaling. A non-issue. One authorization redirect and one outbound HTTPS call per login; ~50–150 ms from mainland China, ~200–400 ms elsewhere. Fully stateless and horizontally scalable. Because this flow uses per-user OAuth tokens rather than the global access_token, there is no shared-token quota bottleneck.

Failure modes to instrument and alert on:

• errcode 40029 (invalid code) and 40163 (code already used — the classic double-submit/back-button case); these look like user error but often indicate a bug.
• Callback URL or domain mismatch: WeChat renders its own Chinese error page, so the failure never reaches our logs. Verify config after every environment change.
• unionid absent → duplicate accounts, discovered weeks later as inflated user counts.
• AppSecret rotation without a deploy → total login outage; document the paired rotation.
• User abandons the QR scan → no callback fires at all; detect via funnel drop-off, not errors.
• Hosting outside mainland China adds noticeable latency to the redirect hop for the target audience.

Ramp-up. Low: a Laravel developer familiar with Socialite is productive in half a day. The non-obvious parts are all WeChat-specific — error-as-200 semantics, openid vs unionid, and the in-app-browser/QR incompatibility. Front-load those in the spike; the second one especially, since it determines whether this package is a complete solution or one half of a two-driver product.