Getting Started

This is a Socialite driver for Sina Weibo, distributed as a subtree split of SocialiteProviders/Providers. It plugs into Laravel Socialite — there is no Weibo-specific SDK, you just add a driver name (weibo) to the standard Socialite flow. Last release was 2020-12-01, so treat it as a thin, mostly-stable adapter rather than an actively maintained integration; verify compatibility with your Socialite/Laravel version before committing.

Install:

composer require socialiteproviders/weibo

(The provider pulls in socialiteproviders/manager, which supplies the SocialiteWasCalled event and the AbstractProvider/User base classes.)

Add credentials to config/services.php:

'weibo' => [
    'client_id'     => env('WEIBO_CLIENT_ID'),
    'client_secret' => env('WEIBO_CLIENT_SECRET'),
    'redirect'      => env('WEIBO_REDIRECT_URI'),
],

protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        \SocialiteProviders\Weibo\WeiboExtendSocialite::class.'@handle',
    ],
];

On Laravel 11+/12, either use ->withEvents([...]) in bootstrap/app.php or, most portable, listen manually in AppServiceProvider::boot():

Event::listen(
    \SocialiteProviders\Manager\SocialiteWasCalled::class,
    \SocialiteProviders\Weibo\WeiboExtendSocialite::class
);

Two controller actions are usually enough to validate the whole integration:

public function redirect()
{
    return Socialite::driver('weibo')->redirect();
}

public function callback()
{
    $weiboUser = Socialite::driver('weibo')->user();

    return [
        'id'     => $weiboUser->getId(),
        'name'   => $weiboUser->getName(),
        'handle' => $weiboUser->getNickname(),   // screen_name
        'avatar' => $weiboUser->getAvatar(),
    ];
}

Look first at vendor/socialiteproviders/weibo/src/Provider.php (endpoints, scopes, field mapping) and the SocialiteProviders "Manager" README for the event-registration syntax matching your Laravel version. The first real-world use case is Weibo login for a Chinese-market app, typically paired with a local account so users can bind/unbind.

Implementation Patterns

Standard OAuth login flow. Redirect → Weibo authorize page → callback → exchange code for token → fetch /2/users/show.json. Keep the default state validation on; don't disable it for a web login flow.

Mapping to your User model. Wrap the Socialite call in a small service so the rest of the app doesn't import Socialite:

$social = Socialite::driver('weibo')->user();

$user = User::updateOrCreate(
    ['weibo_id' => $social->getId()],
    [
        'name'      => $social->getName() ?: $social->getNickname(),
        'nickname'  => $social->getNickname(),
        'avatar'    => $social->getAvatar(),
        'email'     => $social->getEmail(), // may be null — see Gotchas
    ]
);

Use the numeric id (or idstr from getRaw() if you need it as a string) as the stable key; don't use screen_name, which users can change.

Binding an existing account. Because Weibo often doesn't supply an email you can trust, the common pattern is: if a local user is logged in, attach the Weibo identity; otherwise, create a user with a placeholder email and require profile completion later. Guard against two local accounts binding to the same weibo_id.

Capturing extra profile data. The raw payload contains more than the mapped fields (location, description, gender, followers_count, verified, avatar_hd). Read via getRaw() and store in a JSON column if you need it:

$raw = Socialite::driver('weibo')->user()->getRaw();
$user->weibo_profile = Arr::only($raw, [
    'location', 'description', 'gender',
    'followers_count', 'friends_count', 'verified',
]);

Scopes. Request additional scopes when you need them; Weibo joins them with commas:

return Socialite::driver('weibo')
    ->scopes(['email'])
    ->redirect();

Only request scopes your Weibo app has been approved for — unapproved scopes typically cause authorization failures rather than a soft denial.

Testing / local development. Socialite has no built-in fake for this provider, so stub the driver in feature tests:

$socialite = Mockery::mock(\Laravel\Socialite\Contracts\Provider::class);
$socialite->shouldReceive('user')->andReturn(
    (new \Laravel\Socialite\Two\User)->map([
        'id' => '123', 'nickname' => 'tester', 'name' => 'Tester',
        'email' => '[email protected]', 'avatar' => 'https://…',
    ])
);
Socialite::shouldReceive('driver')->with('weibo')->andReturn($socialite);

Alternatively, write a small WeiboService around the provider so you can mock one class in your app rather than Socialite's facade.

Account linking UI. Expose "login with Weibo" and "bind Weibo" as the same controller with a flag; on the callback, branch on auth()->check() to decide create-vs-attach. Store tokens only if you need to call Weibo APIs on the user's behalf — for pure login, don't persist them.

Gotchas and Tips

The uid requirement. Weibo's /2/users/show.json requires both access_token and the numeric uid that came back in the token response. The provider has to capture that uid from the token exchange and reuse it when fetching the user. If you call userFromToken() or userFromTokenAndSecret() (stateless / API style) and it fails, this is why — those paths don't have the token-response body. Do a raw users/show call in that case.
getEmail() is frequently null. Weibo only returns email under an approved email scope, and many apps never get it. Treat email as optional and never assume it's unique-able for account matching.
Numeric id vs idstr. id is a large number that can overflow 32-bit integers or lose precision in JSON parsing. Store it as a string (idstr is the canonical string form) if you plan to migrate or index on it.
Exact redirect URI matching. Weibo (open.weibo.com) requires the callback URL configured in the app console to match services.weibo.redirect byte-for-byte, including trailing slash and scheme. http://localhost doesn't work — use a tunnel or a registered domain.
No refresh-token support. The token response includes expires_in and remind_in, but the provider doesn't implement refreshToken(). If you need long-lived API access, persist the token and implement the oauth2/access_token refresh (grant_type=refresh_token) yourself.
Package is stale (2020). Check the installed version against your Socialite major version. If composer require resolves to something incompatible with laravel/socialite 5.x, you may need to fork or pin. Also check the Manager package version — the event registration API changed across major versions (and again for Laravel 11's bootstrap/app.php).
Debugging a failed callback. The most common failure is on the token exchange (wrong secret, redirect mismatch) or the user fetch (missing uid, rate limit). Log $e->getMessage() from Socialite::driver('weibo')->user() and, on failure, dump the raw token response if you've overridden the provider.
Network reachability. Weibo endpoints can be slow or blocked from servers outside mainland China. Consider a proxy or a nearby region for the callback handler — but keep the redirect URI on your public host.
Extension points. Subclass the packaged Provider, register it under a different driver name, and override getUserByToken() / mapUserToObject() if you need to send uid explicitly or map additional fields. Register via Socialite::extend('weibo-custom', fn () => ...) rather than editing vendor files.
Rate limits. users/show is rate-limited per token; cache the mapped profile for the session instead of calling Weibo on every page load.
State/CSRF is on by default — don't flip to ->stateless() on the web login flow just because it's easier; you'll lose replay protection.

Weibo Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips