Wechat Work Contracts Laravel Package

Getting Started

Install the contracts package and inspect composer.json, README, src/, and the changelog/diff between 0.0.5 and 1.0.2 before adopting it:

composer require tourze/wechat-work-contracts

This package provides contracts/interfaces for WeChat Work/WeCom integration. It is not an end-to-end SDK, so the first practical use case is to define your own adapter implementation and bind it into Laravel’s container.

Start by finding the contract you need in src/, for example the interface representing message sending, access-token handling, contacts/departments, agents, or callbacks. Then bind an implementation in a service provider:

// app/Providers/AppServiceProvider.php
public function register(): void
{
    $this->app->bind(
        \Tourze\WechatWorkContracts\SomeContract::class, // replace with the actual interface
        \App\Integrations\WeCom\SomeImplementation::class
    );
}

Use constructor injection in application services, jobs, and actions:

final class SendWeComNotification
{
    public function __construct(
        private readonly \Tourze\WechatWorkContracts\SomeContract $client
    ) {}

    public function handle(): void
    {
        // Call the contract, not a vendor-specific SDK directly.
    }
}

Treat 1.0.2 as the stable 1.x line. Because the jump is from 0.0.5 to 1.0.2, review the full changelog/diff for breaking signature changes before upgrading existing code.

Implementation Patterns

• Bind interfaces to adapters. Keep WeCom-specific HTTP, auth, retry, and payload logic in your own implementation classes. Application code should depend on the package contracts.
• Use Laravel’s container consistently. Register bindings in a dedicated WeComServiceProvider rather than scattering new calls. This makes testing and replacement easier.
• Wrap the contracts in a small application service. Expose methods like sendText(), sendTextCard(), getUser(), or syncDepartment() from your own service so controllers and jobs do not know WeCom payload details.
• Use contracts in queued jobs. Inject the contract into job constructors, then resolve the implementation through the container when the job runs. This keeps retries and serialization clean.
• Prefer decoration for cross-cutting concerns. Add logging, metrics, token refresh, or retry behavior by decorating your implementation rather than modifying the package contracts.
• Test against the contracts. In unit tests, mock or fake the interface. In integration tests, bind a fake implementation that records calls or returns fixed payloads.
• Check for a service provider. Look in composer.json under extra.laravel.providers. Contracts-only packages may not ship one, so your app may need to register bindings manually.
• Pin compatible versions. If other internal packages rely on these contracts, require a compatible ^1.0 constraint across the application to avoid mixed contract majors.
• Review the diff before upgrade. Since release notes only link to the full changelog, inspect changed interfaces and method signatures. Contracts changes are especially breaking for classes that implement them.

Gotchas and Tips

• Contracts are not implementations. A common failure is injecting an interface without binding it, causing Laravel’s “target is not instantiable” container error. Confirm every required contract has a binding.
• Upgrading from 0.0.5 may be breaking. Even though 1.0.2 is a patch on 1.x, moving from 0.x to 1.x often includes incompatible API changes. Search your codebase for implementations of package interfaces and run static analysis after upgrading.
• Contract changes break implementors first. A changed method signature can break your adapter classes even if call sites look unchanged. Run PHPStan/Psalm and your test suite after composer updates.
• Do not leak WeCom payloads into domain code. Normalize arrays, XML/JSON payloads, and WeCom-specific error codes at the adapter boundary.
• Handle access tokens deliberately. WeCom access tokens are short-lived and rate-limited. Cache them and refresh on expiry or relevant error codes; do not fetch a token per request.
• Callbacks need verification and decryption. WeCom callback URLs often require signature verification and AES message decryption. If the package only provides contracts, implement or delegate this carefully.
• Watch configuration caching. After changing bindings or config, run php artisan config:clear and composer dump-autoload when debugging container resolution.
• Use extension points instead of forking. Implement the contracts, decorate existing implementations, or bind alternate adapters. Avoid editing vendor code.
• Keep the changelog link in upgrade reviews. The 1.0.2 notes are minimal; the compare link is the authoritative source for patch-level changes.