Shopify Laravel Package

Getting Started

• Install only the provider you need, not the whole monorepo: composer require socialiteproviders/<provider> (e.g. socialiteproviders/github, socialiteproviders/steam). Composer will pull in socialiteproviders/manager automatically — that's the shared glue package.
• Register the provider with Socialite via the SocialiteWasCalled event. On Laravel 10 and earlier add it to EventServiceProvider::$listen; on Laravel 11/12 use bootstrap/app.php:

  // Laravel 11+
  ->withEvents(discover: [
      \SocialiteProviders\Manager\SocialiteWasCalled::class => [
          \SocialiteProviders\Steam\SteamExtendSocialite::class.'@handle',
      ],
  ])
  

• Add the credential block to config/services.php — the array key must match the driver string you pass to Socialite::driver():

  'steam' => [
      'client_id' => env('STEAM_CLIENT_ID'),
      'client_secret' => env('STEAM_CLIENT_SECRET'),
      'redirect' => env('STEAM_REDIRECT_URI'),
  ],
  

• First use case: the standard two-route redirect/callback dance.

  Route::get('/auth/redirect', fn () => Socialite::driver('steam')->redirect());
  Route::get('/auth/callback', function () {
      $user = Socialite::driver('steam')->user();
      // $user->getId(), ->getName(), ->getEmail(), ->getAvatar()
  });
  

• Where to look first when something is off: the provider's own README in SocialiteProviders/Providers (each provider folder has one), then the *ExtendSocialite class for the driver name it registers, then config/services.php.

Implementation Patterns

• Config-driven driver name. Providers register a string key (sometimes not what you'd guess — steam vs steamopenid, twitch vs twitch_helix). Always confirm from the provider's ServiceProvider/ExtendSocialite file rather than assuming.
• Stateless flows for APIs. For SPA/mobile backends where you don't want session state: Socialite::driver('x')->stateless()->user() in the callback, paired with stateless()->redirect() on the redirect leg. Requires you to handle state yourself if you care about CSRF.
• Extra scopes and parameters. Prefer ->scopes([...]) (merges with provider defaults) over ->with(['scope' => ...]) (overrides). Provider-specific extras go through ->with([...]), e.g. Google's access_type/prompt, or ->setScopes() on the driver instance.
• Refresh tokens. $user = Socialite::driver('x')->user(); $user->refreshToken; $user->expiresIn; then Socialite::driver('x')->refreshToken($token)->user() (provider support varies). Persist refreshToken encrypted if you store it.
• Multi-tenant / white-label. Because credentials live in config/services.php, you can register per-tenant config at runtime (config(['services.github.client_id' => ...])) before calling Socialite::driver() — cleaner than duplicating drivers.
• Linking providers to existing accounts. Use the SocialiteUser ID plus provider name as a composite key in an oauth_accounts table; keep email matching as a fallback with an explicit "verified email only" guard.
• Extending / bespoke providers. Depend on socialiteproviders/manager directly and extend SocialiteProviders\Manager\OAuth2\AbstractProvider (and User) to write your own provider while reusing the event-listener wiring.
• Testing. Fake the HTTP layer (Http::fake()) or swap the Socialite driver with a mock returning a real SocialiteUser; don't hit live OAuth endpoints in CI. Assert on your callback route, not on the package.

Gotchas and Tips

• Exact callback URI. Most invalid_client / redirect_uri_mismatch failures come from a trailing slash or http vs https difference between services.php and the provider console. Match byte-for-byte.
• Event registration is the #1 "driver not supported" cause. If Socialite::driver('steam') throws InvalidArgumentException, the SocialiteWasCalled listener isn't wired. On Laravel 11+ with event discovery, cached events (php artisan event:cache) can also hide newly registered listeners — clear it.
• php artisan config:cache after editing services.php. In production deploys, stale config is the usual suspect for "wrong client id" after a credential rotation.
• Deprecations are handled in manager, not your app. 4.3.0 swapped the deprecated Request::get() for input() inside the manager package's request handling (atymic, PR #1462). This is a drop-in patch — no API change, no config change, no breaking behaviour. Upgrade with composer update socialiteproviders/manager and you'll stop seeing the PHP 8.x/Laravel 11+ deprecation noise in logs. Nothing else to do.
• Pin socialiteproviders/manager if you use many providers. Old provider packages sometimes constrain manager to a narrow range, so adding a second provider can conflict. composer why socialiteproviders/manager diagnoses it.
• Provider-specific surprises:
  • OAuth1 providers (Twitter) are a separate lineage with a different base class and stricter token handling.
  • Providers like Steam use OpenID rather than OAuth2 and simply won't return an email.
  • Some providers require you to enable APIs in their console before getEmail() returns anything (Google, Microsoft) — a null email is often config, not a bug.
• Error handling. Wrap ->user() in a try/catch for \Laravel\Socialite\Two\InvalidStateException (user denied / session expired) and redirect to a friendly error page rather than a 500.
• Session dependence. Non-stateless flows need the session cookie set on the redirect request; API-only routes or api middleware will silently break state checks.
• Debugging tip. Socialite::driver('x')->getAuthUrl() (or dd'ing the redirect Location header) exposes exactly what scopes/params were sent — faster than reading the provider source.
• Extension point. Override getUserByToken() in a subclassed provider when the provider's user payload needs normalising (nested data envelopes are common), and bind your subclass rather than patching vendor code.