Wechat Mini Program Custom Service Bundle Laravel Package

Getting Started

Note: the 0.1.0 release notes contain only a compare link with no changelog body, so this assessment is derived from package metadata and the 0.0.2 → 0.1.0 cadence rather than from documented changes. Treat version-specific claims as unverified until you read the diff.

1. Read composer.json first, not the README. Tourze publishes Symfony bundles, not Laravel packages. Check for symfony/framework-bundle, symfony/dependency-injection, doctrine/orm, and tourze/* siblings. If those are hard requirements, this is not a composer require-and-go dependency in a Laravel app — you'll be pulling Symfony's kernel, DI compiler passes, and possibly Doctrine into an Illuminate container that doesn't run them.
2. Locate the actual send path. Search the source for classes matching *CustomService* / *Service and for the WeChat endpoints /cgi-bin/message/custom/send and /cgi-bin/token. That's the entire functional surface: exchange credentials for an access_token, then POST a JSON message body to a specific openid.
3. Expect attribute/annotation-driven config. Tourze bundles typically register services via PHP attributes and auto-configuration rather than a publishable config file. In Laravel you will have to instantiate the send service manually and inject the HTTP client and token provider yourself — there is no config/wechat.php to publish.
4. First use case: send a plain text customer-service message to a user who has messaged your mini program within the last 48 hours. That 48-hour session window is the constraint that shapes every real integration, so validate the happy path against it before building anything else.

If you only need to call the WeChat custom-service API from Laravel, you are likely better off with a thin Guzzle/Http:: wrapper than adopting this bundle. Adopt it if you are already inside a Symfony runtime or a Tourze bundle stack.

Implementation Patterns

• Centralize the access token. WeChat issues one global access_token per app (7200s TTL, and fetching a new one invalidates the old). Whatever this bundle does internally, ensure you are not calling token acquisition per-request. Wrap it in a cache with a mutex/short lock; concurrent refreshes cause 40001 storms.
• Wrap the sender in your own adapter. Define a small CustomerServiceSender interface in your app with sendText(string $openid, string $text): void and bind the bundle's service behind it. Given the 0.x version and empty changelog, this insulation layer is what makes the next release cheap to absorb.
• Queue outbound sends. Customer-service messages are I/O against a rate-limited external API; do them in a job with $tries/backoff rather than inline in a request. Classify failures: retryable (-1 system busy, 45047 rate limit) vs. terminal (45015 outside 48h window, 43004 not followed, 40003 bad openid).
• Handle the inbound callback in its own route. WeChat's push callback expects a 200 within ~5 seconds, then retries. Verify the signature, respond immediately, and dispatch the parsed message to a job. Do not let the bundle's parser run inside your main request cycle if it does synchronous work.
• Persist inbound messages. Store openid + timestamp on every inbound event so you can know whether the 48-hour window is open before attempting a send, rather than discovering it via 45015.
• Test against a fake HTTP client. Bind a fake for the token endpoint and send endpoint in your test suite; no live credentials required for the majority of coverage.

Gotchas and Tips

• It is a Symfony bundle, not a Laravel package. No ServiceProvider, no Facade, no config publishing, no auto-discovery. This is the single largest source of friction and the reason 0.1.0's changes are hard to assess from the notes alone.
• Pre-1.0 API instability. Jumping 0.0.2 → 0.1.0 with no changelog body means you cannot diff intent. Pin the exact version in composer.json ("0.1.0", not ^0.1) and review the diff before bumping.
• IP whitelist. WeChat requires the server IP to be whitelisted for token acquisition in production. This will work locally and fail in CI/staging with 40164 — a classic false "the package is broken" signal.
• Encoding mismatch. Customer-service payloads use UTF-8 JSON; the callback push uses XML. Ensure your JSON encode doesn't drop unicode (JSON_UNESCAPED_UNICODE is worth setting for readable logs) and that any XML parser handles CDATA.
• Error responses return HTTP 200. WeChat signals failure in the body's errcode, not the status code. If the bundle's HTTP client only throws on non-2xx, failures will pass silently. Log the raw body.
• 45015 is a state bug, not an API bug. Almost every "message won't send" report is the 48-hour window. Track inbound timestamps and refuse to enqueue sends you know will fail.
• Extension points are likely thin. If the bundle hard-codes its HTTP client or token storage, you may need to decorate services via the Symfony container rather than config. Check for interfaces (*Interface / *Aware) before forking — a decorator on a TokenProviderInterface is far cheaper than a patch.
• Chinese-language docs only. WeChat's official error code table and the 客服消息 payload schema are in Chinese; keep a bookmark. The package source is likely to be the most reliable documentation you have for this version.