Wechat Official Account Qrcode Bundle Laravel Package

Getting Started

This is an early (0.0.1) Symfony bundle for generating WeChat Official Account QR codes, not a native Laravel package. It wraps the WeChat qrcode/create API to produce temporary or permanent QR codes used for login, binding, or channel attribution.

Minimal steps:

1. composer require tourze/wechat-official-account-qrcode-bundle
2. Because there is no Laravel auto-discovery, manually register the bundle's services. Inspect src/Resources/config/services.yaml (or equivalent) and replicate bindings in a Laravel service provider. The bundle likely depends on tourze/wechat-official-account-bundle for access-token management—install and configure that first.
3. Configure credentials: app_id, app_secret, token, and aes_key (if using encrypted callbacks). In Symfony this lives under config/packages/wechat_official_account_qrcode.yaml; in Laravel you'll need to publish/copy that structure into config/wechat.php and bind values manually.
4. First use case: generate a temporary QR code for user login/binding. Inject the QR code service and call something like createTemporaryQrCode($sceneInt, $expireSeconds). The response contains a ticket; build the scannable URL as https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=<urlencoded_ticket>.

Where to look first: src/Service/ for the QR code generation class, src/DependencyInjection/ for config keys, and any tests for real usage examples. The README may be sparse at 0.0.1—rely on the source.

Implementation Patterns

• Temporary vs permanent QR codes: Temporary codes expire (max 30 days) and use an integer scene from 1–100000. Permanent codes never expire but are limited to 100,000 total per account, and use a string scene of 1–64 characters. Choose based on whether the scene represents a one-time login token or a stable channel identifier.
• Scene design: Prefix scene values to avoid collisions (e.g., login_123, bind_456). Store the mapping scene -> user_id / purpose / created_at in your database so the callback handler can resolve it.
• Callback handling: WeChat pushes scan events to your configured URL as XML. The event is SCAN (already followed) or subscribe (new follower) with EventKey containing the scene. Write a controller that parses the XML, extracts EventKey, looks up the scene, and updates your application state (e.g., mark login token as scanned).
• Login flow: Generate a temporary QR with a random unguessable scene, persist it with a short TTL, return the QR image URL to the frontend. Poll a status endpoint from the browser, or push via websocket, until the callback marks the token as scanned. Then exchange the token for a session.
• Service wiring in Laravel: Create a service provider that binds the bundle's interfaces/classes. If the bundle uses Symfony's ContainerInterface or event dispatcher, provide Laravel-compatible implementations or use a bridge like symfony/console only where needed. Prefer constructor injection of the QR service into your own actions/jobs.
• Token management: Rely on tourze/wechat-official-account-bundle (or whatever it depends on) to fetch and cache the access token. Do not fetch tokens manually; WeChat rate-limits token requests and invalidates old tokens when a new one is issued.

Gotchas and Tips

• Not Laravel-native: The biggest pitfall. There is no config publishing, no facade, no auto-discovery. Budget time to manually wire services and config. If you need a quick Laravel solution, consider laravel/socialite with a WeChat driver for login—but this bundle gives you finer control over QR scenes and permanent codes.
• Access token singleton: WeChat allows only one valid access token per app at a time. If your Laravel app and another service both fetch tokens, they will invalidate each other. Centralize token fetching through the bundle's token manager and ensure only one process refreshes it (use a cache lock).
• QR code limits: Temporary QR codes have a daily creation limit (100,000) and permanent codes are capped at 100,000 total for the account lifetime. Monitor usage and reuse permanent codes for stable channels.
• Callback response time: WeChat expects a response within 5 seconds. Keep your callback handler fast—queue heavy work. If you fail to respond, WeChat retries and may disable the callback URL.
• XML parsing: WeChat callbacks are XML, not JSON. Use simplexml_load_string with libxml_disable_entity_loader(true) for safety, or a dedicated parser. Log the raw XML during development.
• Debugging: Enable verbose logging around the QR creation call—log the request payload, response ticket, and any error codes (errcode, errmsg). Common errors: invalid scene (out of range), invalid access token, or rate limit exceeded.
• Version pinning: 0.0.1 has no backwards-compatibility promise. Pin the exact version in composer.json and review changelogs before upgrading. The API surface (method names, config keys) may change.
• Extension points: The bundle likely uses Symfony's DI and event dispatcher. In Laravel you can override service classes by binding your own implementations after the bundle's provider runs. If it dispatches events, you may need to bridge Symfony's dispatcher to Laravel's or replace it.