Wechat Work Kefu Bundle Laravel Package

Getting Started

This is a 0.0.x release of a Symfony-style bundle (tourze/wechat-work-kefu-bundle) for WeChat Work (企业微信) customer-service messaging, so treat the first hour as reconnaissance rather than integration.

1. Pin the exact version — composer require tourze/wechat-work-kefu-bundle:0.0.2 (no caret). At 0.0.x there is no backwards-compatibility promise.
2. Read the vendor tree before the README — vendor/tourze/wechat-work-kefu-bundle/src/ for the entry classes, Resources/config/services.yaml (or config/) for service IDs and constructor arguments, and tests/ for the only reliable usage examples at this stage. The 0.0.2 notes are a bare changelog link, so run git diff 0.0.1...0.0.2 against the upstream repo to see what actually moved.
3. Expect Symfony wiring, not Laravel auto-discovery. Look for a *Bundle class, a DependencyInjection/Extension and named container parameters. Your first Laravel task is a thin bridge: a service provider that registers the classes you need and maps Symfony parameters onto config/wechat-work-kefu.php.
4. First use case: send a single customer-service text message to a known external user ID via the bundle's client/service, with credentials supplied from config/services.php-style config backed by .env. Get one outbound call working before touching inbound callbacks — callbacks add encryption and a 5-second response deadline.

Implementation Patterns

Bridge the container, don't fight it. Register the package's core client as a singleton in a dedicated WechatWorkKefuServiceProvider, translating constructor arguments from your own config file. Avoid resolving bundle internals directly in controllers.

$this->app->singleton(KefuClient::class, fn ($app) => new KefuClient(
    corpId: config('wechat-work-kefu.corp_id'),
    secret: config('wechat-work-kefu.secret'),
    agentId: config('wechat-work-kefu.agent_id'),
));

Config over parameters. Mirror every Symfony container parameter the bundle expects into one Laravel config file, then bind them explicitly. This keeps the adaptation in one place when 0.0.3 renames something.

Outbound work belongs in jobs. Wrap message sends in a queued job with retry/backoff. WeChat Work rate limits and token expiry make synchronous sends in a request cycle fragile.

Inbound callbacks as a dedicated controller. Route the callback URL to a single-action controller that (a) logs the raw body, (b) hands off to the bundle's decryption/verification service, (c) responds immediately, and (d) pushes the parsed event onto a queue. Never do business logic inside the 5-second window.

Test against fakes, not the network. Since the package is pre-1.0 and lightly documented, write contract tests around your own wrapper interface (e.g. KefuGateway), with a fake implementation for feature tests and one integration test tagged @group external that hits the real API only in CI on demand.

Version-guard the upgrade. Because release notes carry no detail, keep a short docs/wechat-work-kefu-upgrade.md noting which classes/config keys you depend on, so the 0.0.1 → 0.0.2 → 0.0.3 diffs are reviewable in minutes.

Gotchas and Tips

• 0.0.2 ships no changelog in the release body. The only signal is the GitHub compare link. Diff the tags and skim changed service definitions before upgrading; constructor signature changes are the most likely break at this stage.
• No Laravel package discovery. If there is no extra.laravel block in composer.json, nothing registers itself. Confirm with composer show tourze/wechat-work-kefu-bundle and check composer.json for Illuminate\Support\ServiceProvider in extra.
• Access-token caching is the usual first bug. WeChat Work tokens expire (~7200s) and are capped per corp/secret. Make the token store a singleton backed by Laravel cache; do not fetch a token per request.
• Callback encryption. Inbound events are AES-encrypted with EncodingAESKey and carry a msg_signature. Log the raw body before decryption — misconfigured keys produce opaque failures otherwise.
• Network constraints. The WeChat Work API requires your server IP to be whitelisted in the admin console; local development needs a tunnel and the matching IP registered. Timeouts against qyapi.weixin.qq.com are almost always whitelist or DNS, not code.
• Extension points are limited. Prefer decorating the bundle's client behind your own interface over subclassing its concrete classes — that way an upstream rename in 0.0.3 only touches one adapter.
• Watch for hardcoded Symfony assumptions: %kernel.debug%, kernel.cache_dir, or RequestStack usage will not resolve cleanly in Laravel. Bind substitutes in your provider or patch via a small compatibility layer.
• Do not adopt for production yet unless you are prepared to vendor-fork. At 0.0.2 the sensible posture is: spike it behind an interface, keep the wrapper, and re-evaluate once the package reaches a documented 0.1.x.