Wechat Web Laravel Package

Product Decisions This Supports

Market-entry and login-funnel decisions for China-facing web products. This package is the Laravel/Socialite glue for WeChat Open Platform "website application" login (网站应用 — the QR-code "scan to sign in" flow on open.weixin.qq.com). It lets you answer, cheaply, whether WeChat sign-in moves your activation and registration-conversion numbers for mainland users. WeChat is the de facto "Sign in with Google" for that market; without it you are asking users to create yet another password.

Specifically, it informs:

• Feature bet: social login for China. A one-to-three-day spike (composer require, config, callback route, profile mapping) yields a real conversion datapoint before you commit roadmap capacity to a China-localized auth stack.
• Build vs. buy vs. fork. The package is a thin OAuth2 driver (~a few hundred lines wrapping Socialite's abstract provider). The "buy" here is really "adopt and own": negligible code, but you inherit the maintenance. Frame the decision as fork-and-own a 200-line driver versus write the driver in-house (similar effort) versus adopt a full WeChat SDK (larger surface, actively maintained).
• Identity architecture: openid vs. unionid. The Open Platform flow returns a unionid when your app is bound to a WeChat Open Platform account, which is what lets you stitch one human across your website, official account, and mini program. Deciding whether you need a cross-channel identity graph is a product decision this integration forces early — and it is the single most consequential one, because retrofitting identity later is expensive.
• Desktop vs. mobile auth strategy. The QR-connect flow presumes the user is on a desktop browser with a phone in hand. If your traffic is mobile-web, this provider is the wrong primitive and you need Official Account OAuth inside the WeChat in-app browser instead. That segmentation decision belongs on the roadmap, not in the ticket.
• Scope boundary: login only. This gets you authentication and a basic profile. It does not give you payments, JS-SDK sharing, template messages, or mini-program APIs. If the product hypothesis includes any of those, budget for a second integration (likely EasyWeChat) and treat this as a pilot.
• Compliance gate. WeChat login implies collecting a Chinese-market user identifier and profile data — PIPL consent language, ICP filing for the domain, and data-residency review. Surfacing that cost early prevents a late-stage launch blocker.

Use cases it fits: PC web sign-in for mainland consumers, B2B portals where employees/customers authenticate via WeChat, cross-border commerce storefronts targeting Chinese buyers, and account-linking for existing users who already have a WeChat identity.

When to Consider This Package

Consider it when all of these are true:

• You are on Laravel + Laravel Socialite already and want the standard Socialite::driver('weixinweb') ergonomics — no bespoke auth plumbing.
• You need only the Open Platform website-app QR login flow. Nothing else.
• You are comfortable pinning the version, vendoring or forking it, and writing your own tests around the callback, state handling, and error paths.
• You accept it as a time-boxed validation rather than a long-lived dependency with a support contract.
• You have verified your WeChat Open Platform app is approved for 网站应用 and bound to an Open Platform account if you need unionid.

Look elsewhere when:

• You need the in-WeChat-browser flow (公众号网页授权). That is a different provider (socialiteproviders/wechat), a different app type, and different scopes (snsapi_base vs. snsapi_userinfo). Buying the wrong one is the most common failure mode here.
• You need the broader WeChat surface — payments, JS-SDK, customer-service messages, mini programs, media upload. Use an actively maintained full SDK (EasyWeChat is the default answer) rather than stacking single-purpose providers.
• You need a maintained dependency. Last release was 2020-12-01, 29 stars, single-maintainer subtree split from the SocialiteProviders monorepo. It is not abandoned in the sense that the upstream repo absorbs fixes, but it is not a vendor you can point at in a security review and call "supported."
• You need SLAs, security patching commitments, or procurement sign-off on third-party auth code.
• You are mobile-first. QR-scan desktop login will not serve the majority of your traffic.
• You expect WeChat API drift to be handled for you. WeChat has changed token handling, TLS requirements, and endpoint behavior since 2020; assume you or your fork owns that.

The practical middle path most teams take: copy the driver into your own app/Socialite/ namespace, wrap it behind your own WeChatAuthenticator interface, and keep the swap to EasyWeChat a one-file change. At this package's size, that is cheaper than the governance overhead of adding a dependency.

How to Pitch It (Stakeholders)

To executives: WeChat is how roughly a billion people log into things. If our roadmap includes any China-facing web product, "sign in with WeChat" is table stakes, not a differentiator — users bounce at a password form. This package lets us test that hypothesis in days rather than weeks, for effectively zero licensing cost. The strategic value is the learning, not the code: it tells us whether WeChat-authenticated users convert, and it forces us to decide early whether we need a unified cross-channel identity (unionid) — a decision that is cheap now and very expensive after launch.

To engineering: It is a thin Socialite OAuth2 driver for the WeChat Open Platform QR-login flow. Standard redirect / callback pattern, state handled by Socialite, openid/unionid plus basic profile on the callback. Caveats: released 2020, 29 stars, so we treat it as fork-and-own — pin it, vendor or copy it into our namespace, add tests around the callback and token exchange, and put it behind our own interface so we can migrate to EasyWeChat without touching call sites. WeChat tokens are short-lived (access token ~2h, refresh ~30d); we persist what we need for identity and do not rely on the provider for long-lived session management.

To security/compliance: The integration collects a Chinese-market persistent identifier plus profile data. That triggers PIPL consent copy, ICP filing for the callback domain, and a data-flow review on where we store unionid. The dependency itself is small and auditable — the risk is maintenance, not surface area, and we are mitigating it by owning the fork.

Bottom line: Low cost, low commitment, high information value — adopt it as a scoped spike with an explicit expiry date, not as a permanent platform decision.