Wechat Work Mini Program Bundle Laravel Package

Getting Started

This is the first public release (0.0.1) and the release notes contain no changelog, migration notes, or feature list — only a link to the commit range. Treat the package as unvetted scaffolding and budget time for a source read before you commit to it.

Orientation pass (do this first, ~15 minutes):

1. composer require tourze/wechat-work-mini-program-bundle and immediately inspect what landed:
   • composer.json — check the type field. The -bundle suffix and the tourze/* namespace strongly suggest a Symfony bundle, not a Laravel package. There is very likely no Illuminate\Support\ServiceProvider in the tree.
   • src/ for the bundle entry class (typically *Bundle.php extending Symfony\Component\HttpKernel\Bundle\Bundle) and for DependencyInjection/Configuration.php + *Extension.php — that pair tells you exactly which config keys exist.
   • README.md and any docs/ — expect Chinese-language docs or none at all.
2. Map the transitive deps. This bundle almost certainly wraps a lower-level HTTP client package (something like tourze/wechat-work-* or an EasyWeChat-style client). That lower-level package is what you actually want to integrate, not the bundle.
3. Decide your integration path:
   • Preferred: bind the underlying client/SDK directly in a small Laravel service provider of your own. You skip the Symfony DI layer entirely.
   • Fallback: register the Symfony bundle's services manually in a provider if the bundle contains logic you can't cheaply reimplement.

First real use case for a WeChat Work (企业微信) mini program is the login exchange: take the code returned by wx.login() on the client, call the mini program's session endpoint with your corp_id/corp_secret, and get back userid/session_key/openid. Wire that into a single POST /api/login route, cache the access token, and you have a working vertical slice that exercises config, HTTP, and error handling at once.

// config/services.php
'wechat_work' => [
    'corp_id'     => env('WECHAT_WORK_CORP_ID'),
    'corp_secret' => env('WECHAT_WORK_CORP_SECRET'),
    'agent_id'    => env('WECHAT_WORK_AGENT_ID'),
],

// app/Providers/WeChatWorkServiceProvider.php — adapt to the real constructor signature
$this->app->singleton(WeChatWorkClient::class, fn ($app) => new WeChatWorkClient(
    corpId:     config('services.wechat_work.corp_id'),
    corpSecret: config('services.wechat_work.corp_secret'),
));

Do not assume the constructor signature — read it. At 0.0.1 it is unlikely to be stable.

Implementation Patterns

Wrap, don't scatter. Whatever the package exposes, put a thin application-level adapter in front of it and have the rest of your codebase depend on your adapter. Given the pre-1.0 version number, this is the single highest-value decision you'll make: it lets you swap or fork the package without touching call sites.

final class WeChatWorkGateway
{
    public function __construct(private WeChatWorkClient $client) {}

    public function resolveUserFromCode(string $code): WeChatWorkUser
    {
        // normalise the vendor response into a domain object here
    }
}

Token lifecycle belongs in the cache, not in the request. Access tokens are ~7200s and rate-limited per corp. Resolve them through Cache::remember() with a key namespaced by corp_id and agent_id, and refresh proactively rather than on 42001/40014 failures. If the package ships its own token cache, confirm whether it is PSR-6/PSR-16 and whether you can inject a Laravel-backed adapter — otherwise it will silently write to the filesystem under var/cache.

Inject the HTTP client. Laravel's Http facade is Macroable but not a drop-in for PSR-18/PSR-18-style clients. If the package accepts a PSR-18 client, the clean bridge is symfony/http-client (which Laravel ships with) constrained to a single client instance, so you can swap in MockHttpClient in tests. If it hardcodes its own client, that's a real testability cost — note it.

Queue the outbound calls. Message sends, media uploads, and bulk operations are slow and rate-limited. Dispatch a job with ->onQueue('wechat') and ->middleware(RateLimited::by('wechat-work')) from Illuminate\Queue\Middleware\RateLimited rather than calling inline from a controller.

Config as first-class. Mirror every key from the bundle's Configuration.php into config/wechat_work.php, back it with env() at the top level only, and add a boot-time validation (a small assertConfigured() in the provider) so a missing agent_id fails at deploy rather than at first customer request.

Testing seam. In TestCase::setUp(), bind a fake gateway. Because you've wrapped the vendor, the bulk of your suite never touches the package and you only integration-test the adapter with recorded fixtures.

Gotchas and Tips

• It is probably not a Laravel package. The -bundle naming is a Symfony convention. There will be no config/wechat_work.php to publish, no facade, no auto-discovery. Plan for manual wiring. Verify before you promise a timeline.
• 0.0.1 means no API surface guarantees. Anything can change in 0.0.2. Pin exactly ("tourze/wechat-work-mini-program-bundle": "0.0.1") and read every diff before bumping. Do not use a caret range.
• Empty release notes are a red flag, not a formality. There is no record of what this initial tag contains, whether it was ever exercised against the live 企业微信 API, or what the prior private iterations looked like. Check commit count and dates on the linked changelog — a single squashed commit means the code has no review history.
• Check for tests. ls vendor/tourze/wechat-work-mini-program-bundle/tests and look for a CI badge. Absence means you are the QA.
• Symfony DI leakage. If you do register the bundle, watch for services.yaml resource-loading that assumes a Symfony kernel (%kernel.project_dir%, %kernel.debug% parameters). These throw at container compile time in Laravel and are usually easier to bypass than to fix.
• IP allowlist. WeChat Work API calls must originate from a trusted IP configured in the admin console, otherwise you get 60020 not allow to access from your ip. This bites hardest in CI and in serverless/queue-worker environments with rotating egress IPs — which is precisely where you'd want to run the queued jobs from the pattern above. Use a NAT gateway with a fixed IP.
• Token collision across agents. Different agent_ids under the same corp have separate tokens; a shared cache key will cause intermittent 40014s under concurrency. Namespace the key.
• Error handling. 企业微信 returns errcode/errmsg in the JSON body with HTTP 200. Any code that checks only $response->successful() will treat failures as successes. Make your adapter throw a domain exception on non-zero errcode and log the raw payload.
• Extension point to watch: if the bundle exposes an event dispatcher, that's your hook for token-refresh and audit logging. If it doesn't, prefer decorating the underlying client over forking the bundle — forks of unmaintained 0.0.x packages rot fast.
• Documentation gap. Assume you'll be reading Chinese-language WeChat Work API docs alongside the source. Keep a short internal docs/wechat-work.md recording the concrete request/response shapes you've verified — you cannot rely on the package's README to stay accurate.

Verdict: usable only after a deliberate source audit and behind your own adapter. The absence of a changelog means this review cannot confirm what changed or what the package actually does — the next release note should be the trigger to revisit this assessment.