Wechat Mini Program Plugin Bundle Laravel Package

Getting Started

Heads-up before you start: despite the "bundle" name and the Laravel framing, this is a Symfony bundle from the Tourze family, not a Laravel package. There is no config/app.php provider entry, no php artisan vendor:publish, and no facade. In a Laravel codebase you will be bridging it manually (see Implementation Patterns), and you should budget for that before committing.

Minimal steps:

1. composer require tourze/wechat-mini-program-plugin-bundle
2. Register the bundle in config/bundles.php (Symfony) or, in Laravel, in a small bridge service provider that instantiates/registers the bundle's services against Laravel's container.
3. Ensure the WeChat mini program credentials are available — this bundle does not own the HTTP/auth layer; it leans on a sibling client bundle (typically wechat-mini-program-bundle) for the access token. Wire that first, or nothing here will authenticate.
4. Run the Doctrine migration for the plugin table (bin/console doctrine:migrations:migrate), or export the schema and translate it into an Eloquent migration if you are going the Laravel route.
5. Sanity-check the service registration with bin/console debug:container | grep -i plugin — the exact service IDs are your map for the rest of the work.

Where to look first: the Doctrine entity and its repository. That is the stable core of the bundle — everything else (services, commands) is thin sugar around persisting plugin bindings and calling the WeChat wxa/plugin endpoints. Read the entity fields, then the service that syncs it, then the console command if one ships.

First use case: record a plugin binding (mini program app + plugin app id + plugin version) and push it to WeChat so the plugin becomes available in the mini program's runtime. That single write path exercises the whole bundle: container wiring, credentials, HTTP client, persistence, and error mapping.

Implementation Patterns

Treat the entity as the source of truth, the API as a projection. The natural pattern is: write the desired plugin state to the database, then run a sync step that reconciles it with WeChat. This gives you idempotency, an audit trail, and something to diff when WeChat rejects a call. Do not call the WeChat API inline in a controller and then persist — you will end up with rows that do not match reality whenever the API call succeeds but the DB write fails, or vice versa.

Reconciliation job, not fire-and-forget. Wrap the sync in a queued job or scheduled command that iterates bindings and compares against the remote plugin list. WeChat's plugin state can change outside your application (someone unbinds a plugin in the MP admin console), so a periodic pull-and-reconcile is the only way to stay honest. Run it on a schedule, log the diff, and alert on drift.

Environment-scoped version pinning. Plugin versions are a per-environment concern — you almost certainly want a different pinned version in staging than in production, and you want a deliberate promotion step. Key your records on (mini_program_app_id, plugin_app_id) and store the version as data, not as a constant in code. That way promoting a version is a data change you can roll back.

Laravel bridge pattern. If you must use this in Laravel, the least painful shape is:

• Keep the bundle's services out of the request path entirely.
• Use the bundle only inside a queue worker or an artisan command running in a Symfony-kernel context, OR
• Register the handful of classes you actually need as singletons in a WeChatPluginServiceProvider, injecting Laravel's Http client in place of the Symfony one if the bundle allows it via an interface alias.
• Share the database. Let the bundle's Doctrine entity write to the same connection your Eloquent models read from, or vice versa — but pick one owner per table and do not let both write.

Multi-tenant / multi-app. Tourze bundles in this family are usually not tenant-aware. If you serve several mini programs, assume you are adding the tenant key yourself, and add it to every repository query — a missing scope here leaks one client's plugin config into another's.

Cache invalidation as a first-class step. After any successful bind/unbind, invalidate whatever caches the mini program list of plugins on your side. The bundle will not do this for you.

Gotchas and Tips

This is 0.1.0 — pin the exact version. Pre-1.0 Tourze bundles routinely rename services, reshuffle entity fields, and drop classes between minor bumps. Use "tourze/wechat-mini-program-plugin-bundle": "0.1.0" with no caret, and treat every upgrade as a code review of the diff.

The release notes tell you nothing. The 0.1.0 entry is a bare changelog link with no described changes, and 0.0.1 → 0.1.0 is a semver-minor on a 0.x line, which permits anything. Before adopting, read the actual commit diff and the entity/migration changes. If there is a schema change, you need to know that before doctrine:migrations:migrate runs against a shared database.

Symfony bundle in a Laravel app is the main pitfall. No package discovery, no config publishing, $app->register() will not pick up Bundle classes, and Doctrine's EntityManager is not Laravel's Eloquent. If your team is Laravel-only and this is a one-off integration, strongly consider calling the WeChat wxa/plugin endpoints directly from a small Laravel service class. The bundle's value is the persistence scaffold, and you may be re-implementing most of it anyway.

Plugin approval is out-of-band. WeChat requires the mini program to have applied for and been approved for a plugin before binding succeeds. A failing bind often has nothing to do with your code — check the MP admin console first. Error responses are frequently opaque; log the raw request and response body, not just the mapped exception.

Access token contention. If the token comes from a sibling bundle, and you also use the token elsewhere (official account, payment), you will race on refresh. Centralise token acquisition in one place; do not let two bundles each hold their own cache.

Debugging checklist, in order: (1) does debug:container show the services, (2) does the token resolve, (3) does the entity persist correctly, (4) does the API call return a business error code. Most tickets are at step 2 or 3, not 4.

Extension points. The realistic customisation surface is the repository and the sync service. Override by aliasing the bundle's service ID to your own implementation in the container rather than editing vendor code — but note that on a 0.x release the service IDs themselves are unstable, so keep the override in one small, well-commented file that you can re-point on upgrade.