Introduction
Installation
Usage & Setup
Generating the redirect
Resolving users
Handling Invalid State
Create account on first login
Log in on registration
Remember Session
Handling Missing Emails
Provider Avatars
Socialite Providers
Changelog
License

Introduction

Larastream is a third-party package for Laravel Jetstream. It replaces the published authentication and profile scaffolding provided by Laravel Jetstream, with scaffolding that has support for Laravel Socialite.

If you are unfamiliar with Laravel Socialite, it is strongly advised that you take a look at the official documentation.

NOTE

Larastream, like Jetstream, should only be installed on NEW applications, installing Larastream into an existing application will break your applications functionality. It is strongly advised against installing this package within an existing applications.

Installation

Getting started with Larastream is a breeze. With a simple two-step process to get you on your way to creating the next big thing. Inspired by the simplicity of Jetstream's installation process, Larastream follows the same 'installation':

composer require tal7aouy/larastream

php artisan larastream:install

The larastream:install command will overwrite the Jetstream published files which are required for Larastream to work.

Note: If you don't have Laravel Jetstream installed, the above command will walk you through the steps required to install it.

Usage

Once Larastream is installed, it will publish a config file. In this config file, you can define whether or not the packages alterations should be shown, the middleware used to wrap the routes as well as the providers that you wish to use:



return [
    'middleware' => ['web'],
    'providers' => [
        \Tal7aouy\Larastream\Providers::github(),
        \Tal7aouy\Larastream\Providers::facebook(),
        \Tal7aouy\Larastream\Providers::google()
    ],
    'features' => [
        // \Tal7aouy\Larastream\Features::rememberSession(),
    ],
];

Once you’ve defined your providers, you will need to update your services.php config file and create client_id, client_secret and redirect keys for each provider:

'{provider}' => [
    'client_id' => env('{PROVIDER}_CLIENT_ID'),
    'client_secret' => env('{PROVIDER}_CLIENT_SECRET'),
    'redirect' => env('{PROVIDER}_REDIRECT'), // e.g. 'https://your-domain.com/oauth/{provider}/callback'
],

Generating the redirect.

In some cases, you may want to customise how Socialite handles the generation of the redirect to a provider. For example, you may wish to To do this, you may alter the GenerateRedirectForProvider action found in app/Actions/Larastream. For example, you may need to define scopes, the response type (e.g. implicit grant type), or any additional request info:

/**
 * Generates the redirect for a given provider.
 * 
 * @param  string  $provider
 * 
 * @return \Symfony\Component\HttpFoundation\RedirectResponse
 */
public function generate(string $provider)
{
    return Socialite::driver($provider)
        ->scopes(['*'])
        ->with(['response_type' => 'token'])
        ->redirect();
}

Resolving users

By default, Larastream will resolve user information from Socialite using the following logic:

Socialite::driver($provider)->user();

Returning an instance of \Laravel\Socialite\AbstractUser. However, you may wish to customise the way user resolution is done. For example, you may wish to use the stateless method available for some Socialite providers. Larastream makes this easy for you and publishes a ResolveSocialiteUser action to you applications app/Actions/Larastream directory. Simply customise this class with the logic required for your use-casee.

Handling Invalid State

To handle instances where Socialite throws an InvalidStateException a dedicated HandleInvalidState action is made available to you when you first install Larastream. You are free to modify or extend this action according to your needs.

Alternatively, you may write your own action to handle the exception. To do so, you'll need to implement Tal7aouy\Larastream\Contracts\HandlesInvalidState and update the following line in App\Providers\LarastreamServiceProvider

Larastream::handlesInvalidStateUsing(HandleInvalidState::class);

Create account on first login

This feature enables the capability to register a new user account (and team if the Jetstream feature is enabled) when a user attempts to authenticate via the '/login' route.