README_EN.md

EasyWeChat for Laravel

WeChat SDK w7corp/easywechat wrapper for Laravel.

Requirements

• overtrue/laravel-wechat:^7.0 -> Laravel >= 8.0
• overtrue/laravel-wechat:^6.0 -> Laravel/Lumen >= 7.0
• overtrue/laravel-wechat:^5.1 -> Laravel/Lumen >= 5.1

Installation

composer require "overtrue/laravel-wechat"

Config

1. publishe the config file to config directory：

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

2. (Optional) You can add the alias to config/app.php:

'aliases' => [
    // ...
    'EasyWeChat' => Overtrue\LaravelWeChat\EasyWeChat::class,
],

3. Each module basically supports multiple accounts, the default name is default.

Usage

Ignore the CSRF check for WeChat related routes:

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

The following is an example written to receive a server message:

Routes:

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

Note

It must be Route::any, because the WeChat server validation is GET request, and when receiving user messages is POST request!

Then, let's create a controller WeChatController:

<?php

namespace App\Http\Controllers;

use Log;

class WeChatController extends Controller
{
    public function serve()
    {
        Log::info('request arrived.'); 

        $server = app('easywechat.official_account')->getServer();

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

        return $server->serve();
    }
}

OAuth middleware

If you're using middleware, just fill in oauth.callback with any value in app/config/wechat.php (because you won't need it 😄).

1. Register the middleware to app/Http/Kernel.php:

protected $routeMiddleware = [
    // ...
    'easywechat.oauth' => \Overtrue\LaravelWeChat\Middleware\OAuthAuthenticate::class,
];

2. Add the middleware to oauth route:

//...
Route::group(['middleware' => ['web', 'easywechat.oauth']], function () {
    Route::get('/user', function () {
        $user = session('easywechat.oauth_user.default'); // oauth user

        \dd($user);
    });
});

You can also set the config name and scopes as middleware paremeter:

// scopes
Route::group(['middleware' => ['easywechat.oauth:snsapi_userinfo']], function () {
  // ...
});

// account name and scopes:
Route::group(['middleware' => ['easywechat.oauth:default,snsapi_userinfo']], function () {
  // ...
});

The above route defines /user as requiring authorization from WeChat, so in the callback or controller method of this route, you can get the authorized user information from session('easywechat.oauth_user.default').

Mock Authorization

Sometimes we want to go real WeChat authorization process only after local development is completed online, which will reduce our development cost, then you need to do the following two steps.

1. Prepare mock authorization information:

use Illuminate\Support\Arr;
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',
        ]);

If your schema is only snsapi_base, you only need openid.

2. Write the information to the session:

// Similarly, `default` can be replaced with your corresponding other configuration name
session(['easywechat.oauth_user.default' => $user]); 

Note

Be sure to write before calling the OAuth middleware, for example, you can create a global middleware to do this, and just enable it in the development environment.

Events

You can listen to the corresponding events and perform the corresponding actions when they occur.

• OAuth authorized: Overtrue\LaravelWeChat\Events\WeChatUserAuthorized

// The event has the following properties
$event->user; // same as session('easywechat.oauth_user.default')
$event->isNewSession; // if it is a new session (true when first creating a session)
$event->account; // the current account used by the middleware, corresponding to the name of the configuration item in the configuration file

Open Platform Support

You can apply the built-in Overtrue\LaravelWeChat\Traits\HandleOpenPlatformServerEvents to quickly complete the server-side validation for the open platform:

routes/web.php:

Route::any('/open-platform/server', OpenPlatformController::class);

app/Http/Controllers/OpenPlatformController.php:

<?php

namespace App\Http\Controllers;

use Overtrue\LaravelWeChat\Traits\HandleOpenPlatformServerEvents;

class OpenPlatformController extends Controller
{
    public function __invoke(Application $application): \Psr\Http\Message\ResponseInterface
    {
        $app = app('easywechat.open-platform');
        
        return $this->handleServerEvents($app);
    }
}

Note

By default, the following events will be triggered based on the push content of WeChat Open Platform, you can listen to the corresponding events and process them.

• Authorized party successfully authorized: Overtrue\LaravelWeChat\Events\OpenPlatform\Authorized
• Authorized party updates authorization: Overtrue\LaravelWeChat\Events\OpenPlatform\AuthorizeUpdated
• Authorizer deauthorized: Overtrue\LaravelWeChat\Events\OpenPlatform\Unauthorized
• OpenPlatform Push VerifyTicket: Overtrue\LaravelWeChat\Events\OpenPlatform\VerifyTicketRefreshed

// Events have the following properties
$message = $event->payload; // Open Platform event notification content

After configuration http://example.com/open-platform/server is the authorized event receiving URL set for the Open Platform third party application.

For more SDK specific usage, please refer to: https://www.easywechat.com

❤️ Sponsor me

If you like my project and want to support it, click here ❤️

Project supported by JetBrains

Many thanks to Jetbrains for kindly providing a license for me to work on this and other open-source projects.

License

MIT