Wechat Mini Program Security Bundle Laravel Package

Getting Started

Scope of this release: 0.2.1 is a patch bump from 0.2.0 with no published changelog entries — only a compare link. There are no documented features, breaking changes, or deprecations to react to. Treat this as a maintenance release and validate by diffing 0.2.0...0.2.1 in the repository rather than relying on release notes.

Minimal steps

1. Pin explicitly, since patch semantics are unverified:

   composer require tourze/wechat-mini-program-security-bundle:0.2.1
   

2. Read the source before wiring anything. Priority order:
   • src/DependencyInjection/Configuration.php — the actual config tree (this is where undocumented options live)
   • src/DependencyInjection/*Extension.php — which services get registered and under what IDs
   • src/Resources/config/*.yaml — service definitions and constructor arguments
   • The concrete service classes (signature verification, decryption, content-security calls)
3. Confirm the framework assumption. The tourze/*-bundle family is Symfony-first (bundles, Extension classes, service YAML). There is no Laravel service provider or extra.laravel auto-discovery in the typical layout. In Laravel you will not get zero-config registration — plan to wrap it manually.

First use case

Server-side verification of a WeChat Mini Program request (signature check and/or encrypted-payload decryption) before your controller logic runs. That is the smallest slice of value and the easiest to test in isolation — get that working end-to-end before touching anything that calls the WeChat API.

Implementation Patterns

Bridge it into the Laravel container. Register the bundle's services yourself in a dedicated provider and resolve them through the container rather than instantiating directly:

// app/Providers/WechatSecurityServiceProvider.php
public function register(): void
{
    $this->app->singleton(SignatureVerifier::class, function ($app) {
        return new SignatureVerifier(
            token: config('wechat-security.token'),
            // ...map constructor args explicitly
        );
    });
}

Do this deliberately: explicit constructor mapping is your guard against constructor signature changes that patch releases can slip in without a changelog.

Mirror config into config/wechat-security.php. The bundle's Symfony config tree won't be read by Laravel. Translate it once, keep 1:1 key names, and read it only inside the provider — never config() from inside domain code, or you lose the ability to swap the implementation in tests.

Wrap behind your own interface. Expose the bundle behind a narrow contract (RequestVerifier, ContentSecurityChecker) so the third-party classes stay at the edge. Given the project's low documentation surface, this is what makes the dependency replaceable.

Centralize access_token handling. Any class that calls the WeChat API needs a shared token, and WeChat enforces a global token validity window — fetching per-request will invalidate tokens for other processes. Wrap acquisition in a cached provider (Cache::remember with a TTL slightly under the expiry, plus a lock to prevent concurrent refresh storms), refresh on 40001/42001, and retry once.

Use it in middleware for request verification. Verification is cross-cutting; a wechat.verify middleware keeps controllers clean and makes the check trivially testable and skippable per-route.

Testing pattern. Because these services are HTTP clients under the hood, fake at the transport boundary (Http::fake() in Laravel, MockHttpClient in Symfony) rather than mocking the bundle's classes. For crypto/signature paths, use known-good fixtures with fixed timestamps and nonces — deterministic inputs are the only way to make signature assertions stable.

Gotchas and Tips

• Empty changelog is the main risk here. 0.2.1 ships no notes. Run composer update --dry-run and review the actual diff for constructor and service-ID changes before promoting. A patch bump is not evidence of a non-breaking change in a pre-1.0 package.
• Pre-1.0 semver. At 0.x, minor bumps may break. Pin to exact versions in composer.json and upgrade intentionally rather than floating ^0.2.
• Symfony-vs-Laravel mismatch is the biggest time sink. Expect no auto-discovery, no publishable config, no facades. Budget for the provider wrapper as part of initial setup, not as cleanup later.
• Thin documentation. These bundles are frequently scaffolded and lightly documented; generated PHPDoc may not reflect real behavior. The source and its tests are the specification — read the tests first, they encode the actual contract far better than the README.
• Don't leak the token into logs. Signature/decryption failures throw with request context attached; scrub tokens and session keys from exception handlers and Laravel's logger context.
• Clock skew and nonce replay. Signature verification depends on a timestamp window and single-use nonces. Use a cache-backed nonce store with TTL matching the window, and check that your server clock is NTP-synced — otherwise intermittent 401s will look like library bugs.
• Error handling granularity. Distinguish "request is forged" (reject 401/403, log at warning) from "WeChat API is unhappy" (retry, log at error, surface 503). Collapsing them makes incident triage painful.
• Extension point. If the bundle's verification logic doesn't fit your flow, don't patch vendor/. Implement your own verifier against the same contract and keep the package only for the pieces you actually use — the surface area is small enough to reimplement if you hit a wall.
• Monitor upstream. With no changelog discipline, watch the repository's commit history directly for the next release rather than trusting tagged notes.