overtrue/laravel-wechat: the EasyWeChat bridge for Laravel apps that talk to WeChat

The gap between EasyWeChat and a Laravel application

EasyWeChat is a standalone PHP SDK. Laravel applications do not consume standalone SDKs cleanly: you end up constructing an application object in a service provider, deciding where credentials live, and inventing a way for controllers to reach the right account. overtrue/laravel-wechat is the adapter layer that removes that work. It registers a Laravel service provider, publishes a config file, and exposes each WeChat module through the container under names such as easywechat.official_account and easywechat.open_platform.

The audience is narrow and specific. You are building a WeChat official account backend, a website that logs users in through WeChat OAuth, or an open platform third-party application, and you are doing it in Laravel. If your integration lives in a non-Laravel PHP service, this package adds nothing over EasyWeChat itself. The README is explicit that the SDK underneath is w7corp/easywechat, and that the full SDK documentation lives at easywechat.com rather than in this repository.

What the service provider actually registers

The mechanism is Laravel's container plus a published config file. Running the vendor publish command copies the package config into your application, and from there each module resolves through a named binding. The README notes that every module supports multiple accounts, with default as the fallback name. That naming is not cosmetic: it is the key you pass to OAuth middleware parameters and the key you read back from the session.

The request path for a message handler is short. A route receives the WeChat callback, the controller pulls the server object from the official account binding, registers a closure with with(), and returns serve(). The README stresses that the route must accept both GET and POST, because WeChat verifies the endpoint with GET and delivers user messages with POST. Getting that wrong produces a verification failure that looks like a credentials problem.

OAuth is handled by middleware rather than by controller code. Once OAuthAuthenticate is registered as a route middleware, a route group carrying easywechat.oauth triggers the redirect flow, and the authorized profile appears in the session under a key built from the account name. The README points out that when you use the middleware, the oauth.callback value in the config file is effectively unused, which is a small but real inconsistency between the config surface and the middleware path.

Installing it and serving your first WeChat message

The README's install command pins the 7.2 line, while the most recent release listed for the repository is 8.0.0. Treat the README command as illustrative rather than current, and check the release notes before you pin a constraint.

composer require overtrue/laravel-wechat:^7.2

After Composer finishes, publish the package config. This is what creates the file your account credentials live in.

php artisan vendor:publish --provider="Overtrue\\LaravelWeChat\\ServiceProvider"

WeChat posts to your endpoint without a CSRF token, so the callback route has to be excluded from Laravel's CSRF check. On older Laravel skeletons that means editing the middleware's except list.

protected $except = [
    // ...
    'wechat',
];

On Laravel 11.x the README shows the same exclusion expressed through bootstrap/app.php instead.

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        // ...
        'wechat',
    ]);
})

Finally, a route and a controller. The route must be any, not post, and the controller resolves the server from the container binding and returns its response.

Route::any('/wechat', 'WeChatController@serve');

public function serve()
{
    $server = app('easywechat.official_account')->getServer();

    $server->with(function($message){
        return "欢迎关注 overtrue！";
    });

    return $server->serve();
}

With that in place, WeChat's server verification should succeed and any text message you send to the account should come back with the reply string.

Mocking WeChat OAuth so local development does not require a tunnel

The part of the README worth reading twice is the mock authorization section. Real WeChat OAuth requires a reachable callback URL, which makes local development awkward. The package's answer is to let you fabricate a Socialite user and place it in the session before the OAuth middleware runs.

use Overtrue\Socialite\User as SocialiteUser;

$user = new SocialiteUser([
    'id' => 'mock-openid',
    'name' => 'overtrue',
    'nickname' => 'overtrue',
    'avatar' => 'http://example.com/avatars/overtrue.png',
    'email' => null,
    'original' => [],
    'provider' => 'WeChat',
]);

session(['easywechat.oauth_user.default' => $user]);

The ordering constraint is the whole trick: the session write has to happen before the middleware executes, which in practice means a global middleware enabled only in the development environment. The README also notes that the fields you need to populate depend on scope. Under snsapi_base, an openid is enough; under snsapi_userinfo you should fill the profile fields or your views will render with nulls. This is a testing seam rather than a mock framework, and it will not catch an incorrect scope configuration.

Open platform support and the events it fires

For third-party platform work, the package ships a trait, Overtrue\LaravelWeChat\Traits\HandleOpenPlatformServerEvents, that handles the server-side verification handshake. The README's example controller uses the trait and calls handleServerEvents against the easywechat.open_platform binding. The URL you configure at the platform becomes the authorization event receiver.

Incoming pushes are translated into Laravel events: Authorized, AuthorizeUpdated, Unauthorized and VerifyTicketRefreshed. Each carries a payload property holding the notification content. The VerifyTicketRefreshed event is the one that matters operationally, because the open platform ticket is what lets you act on behalf of authorized accounts, and it arrives as a push rather than as something you poll.

The same event pattern covers OAuth. WeChatUserAuthorized exposes the user, an isNewSession flag that is true the first time a session is created, and the account name the middleware used. That account property is what makes multi-account setups tractable: one listener can branch on which account produced the authorization instead of duplicating listeners per account.

Where this package stops and EasyWeChat begins

The clearest limitation is documentation scope. This repository documents the Laravel integration: the provider, the config, the middleware, the events, the open platform trait. It does not document the SDK. The README says so directly and sends you to easywechat.com for anything beyond the integration surface. If you are looking for how a particular official account API call is shaped, you will not find it here.

The second constraint is version coupling. The README's compatibility table ties package major versions to Laravel minimums: 7.x needs Laravel 8.0 or newer, 6.x needs Laravel or Lumen 7.0 or newer, and 5.1 needs 5.1 or newer. Lumen is called out separately: the README states that Lumen is no longer supported by default from 7.x onward. A Lumen application that wants this integration is on its own.

There is also a maintenance signal worth reading plainly. The last push to the repository was on 2026-05-07, and the most recent release, 8.0.0, was published on 2026-03-19, following 7.4.0 on 2025-02-25. The gap between 7.3.0 in March 2024 and 7.4.0 in February 2025 is roughly eleven months. Releases arrive when they arrive; nothing in the README promises a cadence. If your integration depends on a WeChat API change landing quickly, that is a risk you are accepting, and the README offers no support commitment to offset it.

Finally, the README is bilingual in the repository but the primary text is Chinese. The English README exists as README_EN.md, and the code examples in the main file are PHP regardless. Non-Chinese-reading teams will want to check the English file's completeness before relying on it.

Choosing between this and talking to EasyWeChat directly

The real alternative is using w7corp/easywechat directly in a Laravel application and writing your own binding. That is not a trivial difference in effort. Doing it yourself means constructing the application object in a service provider, deciding how credentials are loaded, registering a container binding per account, and writing the OAuth redirect and callback handling that OAuthAuthenticate already provides. You also lose the event classes, which you would otherwise emit from your own controller code.

The trade-off runs the other way too. Direct EasyWeChat use keeps you on the SDK's own release schedule and its own documentation, with no adapter layer to lag behind. If you need an SDK feature the moment it ships, or if your integration is unusual enough that the middleware's session-based flow does not fit, the adapter becomes an obstacle rather than a convenience. The package is also Laravel-only by design; a Symfony or plain PHP service gets nothing from it.

A second, less obvious alternative is writing the WeChat HTTP calls yourself. That is defensible only for very narrow integrations, such as verifying a single webhook signature, where pulling in an SDK and a Laravel adapter is more surface area than the task needs. For anything involving OAuth, message handling or open platform authorization, the SDK's work is not something most teams want to redo.

Licence and the cost of staying current

The package is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are preserved. That is the standard permissive arrangement and places no copyleft obligation on your application code. It says nothing about the underlying SDK's licensing, which is a separate repository, and nothing about WeChat's own platform terms, which govern what you may do with the API regardless of the code's licence. This is a description of the licence text, not legal advice.

Upgrade cost concentrates in two places. The first is the Laravel version floor, since each package major raises it, and the README's table is the thing to check before you upgrade either side. The second is the config file you published: it lives in your application, so changes to the package's config structure do not propagate automatically, and a major upgrade may require you to re-publish and reconcile. The jump from 7.4.0 to 8.0.0 is the live example, and the release notes are where the actual breaking changes are recorded. The README's own install snippet still shows ^7.2, which tells you the documentation trails the release by at least one major version.

Editorial conclusion

Adopt it if you are on Laravel 8 or newer, already committed to EasyWeChat as your WeChat SDK, and want account configuration, OAuth middleware and open platform event handling to live inside Laravel's container instead of a hand-rolled bootstrap. Do not adopt it if you are still on Lumen, since the README states that Lumen support ended with 7.x, or if you need the SDK's full API surface documented in one place, because this package defers that to easywechat.com. Before installing, check your Laravel version against the compatibility table in the README, confirm the CSRF exclusion you will need for the WeChat routes, and read the 8.0.0 release notes to see what changed from 7.4.0, since the README still shows a 7.2 install command.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. overtrue/laravel-wechat on GitHub
4. README
5. Releases