Getting Started

Require joelbutcher/socialstream:^6.3 for Laravel 12 projects; v6.3.0 is the first 6.x release with Laravel 12 support and composer dependency fixes.
Run php artisan socialstream:install to publish the config, migrations, routes, and views, then run php artisan migrate to create the connected_accounts table.
Add the HasConnectedAccounts trait to App\Models\User.
Register OAuth apps with each provider and put credentials in config/services.php / .env; enable the providers you need in config/socialstream.php.
Set each provider’s callback URL to the package OAuth callback route, usually /oauth/{provider}/callback — confirm with php artisan route:list.
First use case: add a “Sign in with GitHub” button to your login/register Blade view and complete one end-to-end login. That validates config, routes, session state, and user creation quickly.
First places to look: config/socialstream.php for providers/features, the published routes/controllers for the OAuth flow, and the HasConnectedAccounts trait for connected-account helpers.

Implementation Patterns

Social login: render the package’s provider buttons or use the Socialstream provider list in Blade. The redirect route starts OAuth; the callback route authenticates or creates the user.
Account linking: let authenticated users connect additional providers from account settings. Use the package routes/components for connect/disconnect flows, and use the HasConnectedAccounts relationship to list connected accounts.
Token access: provider tokens are stored on connected accounts. Retrieve them through the ConnectedAccount model when calling provider APIs; handle refresh/expiry per provider.
Customization: publish views to match your branding. Publish routes/controllers if you need custom redirects, user creation, or email-collision/merge behavior. Prefer events/listeners over editing vendor code where possible.
Framework integration: keep the package routes under the web middleware. With Breeze/Fortify/Jetstream, redirect users to your dashboard after callback and avoid duplicate auth route names.
Testing: use Laravel Socialite fakes in feature tests to cover callback success, account linking, and disconnect behavior without hitting real providers.

Redirect URI mismatches are the most common failure. Match scheme, host, port, and path exactly in the provider dashboard, and clear config cache after changing .env.
Composer conflicts: v6.3.0 includes dependency fixes. If install/update fails, check composer why-not joelbutcher/socialstream 6.3.0 and align Laravel/Socialite constraints. Laravel 12 apps should stay on ^6.3.
Session/state errors: ensure your session driver and APP_URL are correct. The callback needs session middleware; stateless API/mobile flows may require custom handling.
Email collisions: the same email from different providers can create or link accounts unexpectedly. Decide whether to merge, reject, or prompt, and test that path explicitly.
Token storage: check column length and consider encryption/casts for tokens. Never dump tokens into logs or Blade views.
Route/view conflicts: the package registers routes and views. Publish before overriding, and avoid duplicate route names if you customize auth flows.
Debugging: use php artisan route:list --name=oauth, Laravel logs, and Socialite exceptions. Reproduce with one provider first before enabling the full provider set.