Identity Socialstream Laravel Package

Getting Started

This package is a thin adapter that wires Socialstream (identity linking + OAuth onboarding) into the Liberu identity module, so the User model, routes and migrations come from the host module rather than from Socialstream directly. Treat it as glue: almost all behaviour you will debug lives in joelbutcher/socialstream or laravel/socialite.

1. Install alongside the identity module. The package assumes liberusoftware/identity is already installed and booted — install that first, then:

composer require liberusoftware/identity-socialstream
php artisan migrate

2. Where to look first (in this order).

3. First use case — "Sign in with GitHub". Publish config and credentials:

php artisan vendor:publish --tag=socialstream-config

// config/services.php
'github' => [
    'client_id'     => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect'      => env('GITHUB_REDIRECT_URI'), // /oauth/github/callback
],

Then drop the package's button component into your existing login view:

<x-socialstream::socialstream-providers />

Hit /login, click GitHub, and confirm you land back on the dashboard with a row in connected_accounts (Socialstream stores the link there, not only on users).

Implementation Patterns

Existing-user account linking (the 90% case). Socialstream's Connected Accounts panel is what most apps actually want: a signed-in user attaches GitHub/Google to their profile. Don't build this yourself — render the component and gate the settings route with auth + password confirmation if the account is privileged:

Route::middleware(['auth', 'password.confirm'])
    ->get('/user/connected-accounts', fn () => view('settings.connections'));

Creating users from a provider. Keep Socialstream's CreateNewUser action as the single creation path, then extend it rather than duplicating it — e.g. assign the Liberu tenant/workspace or default role in a listener on Registered:

Event::listen(Registered::class, function (Registered $event) {
    $event->user->assignRole('member'); // or attach to current tenant
});

Adding a provider that Socialstream doesn't ship. Register a Socialite driver in your own service provider, then add the name to config('socialstream.providers'). The order matters — the package reads the config at container-build time:

Socialite::extend('okta', fn ($app) => Socialite::buildProvider(
    \SocialiteProviders\Okta\Provider::class,
    config('services.okta')
));

Multi-tenant / API surfaces. For stateless JSON endpoints, Socialstream's session-state flow is not what you want. Use Socialite directly (Socialite::driver('github')->stateless()->userFromToken($token)) and only call into this package's linking service afterwards.

Testing. Never let the suite hit the network. Fake Socialite at the driver level:

Socialite::shouldReceive('driver->user')->andReturn($socialiteUser);

Prefer Http::fake() fallbacks only if you're testing an actual driver class — otherwise a changed GitHub response shape will break CI silently.

Feature flags. Socialstream's features array (generateMissingEmails, createUser, updateUserProfile) is respected by the package's actions; toggle them in config rather than overriding action classes. That keeps you upgrade-safe.

Gotchas and Tips

• Two migrations, one table. If Socialstream's own migration also runs, you get duplicate-column errors on users. Check php artisan migrate:status and disable Socialstream's migrations in its service provider if the identity module already owns them — this is the usual reason people say "the package doesn't work."
• Route name collisions. Both packages publish login/register routes. Run php artisan route:list --name=oauth and --name=login and resolve; the last-registered provider wins, which depends on module boot order.
• Password column must be nullable. Socialite-created users have no password. If users.password is NOT NULL, registration fails with a 500 that looks like a provider error. Also handle password.confirm middleware for these users — they can never pass it until they set one.
• Callback URL is exact. Trailing slash, http vs https, and APP_URL behind a proxy all silently break with invalid_request from the provider. Set APP_URL and TrustProxies before debugging the package.
• Tokens are encrypted with APP_KEY. Rotating the key makes every provider_token unreadable and refresh calls throw DecryptException. Plan key rotation with a re-link prompt.
• provider_token expiry is not automatic. Socialstream links; it does not refresh. Wrap any API call in a check of provider_refresh_token and use Socialite's refreshToken() yourself.
• Adoption risk. 0 stars and 0 dependents means no community triage: pin an exact version in composer.json, read the migration before running it in production, and be prepared to fork. The 2026 release date suggests non-standard tagging — verify with composer show liberusoftware/identity-socialstream rather than trusting the tag.
• Debugging ladder: (1) Socialite::driver('github')->redirect() directly in tinker, (2) the package's callback route, (3) the ConnectedAccount row, (4) the Registered/Connected event. Failures are almost always at step (1) or (4), never in the adapter itself.
• Extension point: if you need custom behaviour (email domain allowlist, provider→role mapping), listen to Socialstream's events or decorate the package's action classes in your own service provider — do not edit vendor/, since the adapter has no upgrade path guarantees.