Social Login Package for Laravel 4
This package is a Laravel 4 service provider for Lusitanian/PHPoAuthLib which provides oAuth support in PHP 5.3+ and is very easy to integrate with any project which requires an oAuth client.
In addition, you may take advantage of the optional controller and model to make it very easy to:
- Log in with a social provider
- Connect an existing user record with a social provider
- Perform requests against the social provider API with each user's unique access token
Supported Services
See the documentation for Lusitanian/PHPoAuthLib for the list of supported services.
Installation Via Composer
Add this to your composer.json file, in the require object:
"mmanos/laravel-social": "dev-master"
After that, run composer install to install the package.
Add the service provider to app/config/app.php
, within the providers
array.
'providers' => array(
// ...
'Mmanos\Social\SocialServiceProvider',
)
Add a class alias to app/config/app.php
, within the aliases
array.
'aliases' => array(
// ...
'Social' => 'Mmanos\Social\Facades\Social',
)
Configuration
Publish the default config file to your application so you can make modifications.
$ php artisan config:publish mmanos/laravel-social
Add your service provider credentials to the published config file: app/config/packages/mmanos/laravel-social/config.php
Basic Usage
Obtain a service class object for a provider.
$service = Social::service('facebook');
Optionally, add a second parameter with the URL which the service needs to redirect to, otherwise it will redirect to the current URL.
$service = Social::service('facebook', 'http://example.com');
Redirect the user to the oAuth log in page for a provider.
return Redirect::to((string) $service->getAuthorizationUri());
For examples of how to integrate with a specific provider, see here.
Using The Provided Controller And Model
For added convenience, use the built-in controller and model to easily log in or connect with a social provider account.
Requirements
This implementation is fairly opinionated and assumes that you want to allow your users to log in or sign up seamlessly with their existing social provider account and associate that social provider account with an existing user record.
It has these requirements:
- You have an existing user record with a numeric primary key
- You are using the Laravel authentication system
- You have the Laravel session system enabled
- You have an app key defined in your config/app.php file so the Crypt class can be used to encrypt the access tokens
Migration
Publish and run the database migrations for this package. This will create a user_providers
table.
$ php artisan migrate:publish mmanos/laravel-social
$ php artisan migrate
Note: You can change the default table name used to store the user provider information by changing the value of the
table
key in the config file.
Model Setup
Add the SocialTrait to your User model definition.
use Mmanos\Social\SocialTrait;
class User extends Eloquent
{
use SocialTrait;
}
Social Login Flow
Simply create a link to the built-in controller to initiate a log in flow. The user will be redirected to the provider login page before they return to your website.
If an existing user is already linked to the provider account, they will be logged in as that user.
If an existing user is not found for the provider account, a new user record will be created and then a link to the provider account will be made before they are logged in as that user.
<a href="{{ route('social-login', array('twitter')) }}">
Log in with Twitter
</a>
To customize where the user is redirected to after the log in flow, add onsuccess
and onerror
parameters.
<a href="{{ route('social-login', array('twitter')) }}?onsuccess=/account&onerror=/login">
Log in with Twitter
</a>
Note: The default redirect location is to the
referer
header. Otherwise/
.
Connecting A Social Account Flow
You can also associate a social provider account to an existing user if they are already logged in.
<a href="{{ route('social-connect', array('twitter')) }}">
Connect Your Twitter Account
</a>
Note: This action also supports the
onsuccess
andonerror
parameters.
Working With Users And Providers
You can fetch all providers linked to a user.
$providers = Auth::user()->providers;
You can check to see if a user is connected to a given provider.
if (Auth::user()->hasProvider('twitter')) {
//
}
You can fetch a single provider instance for a user.
$provider = Auth::user()->provider('twitter');
This package stores an encrypted version of the access_token for each user provider. That way you can easily make API calls to the provider service on behalf of the user.
$result = Auth::user()->provider('twitter')->request('account/verify_credentials.json');
Note: Keep in mind it is possible for an access_token to expire. You can refresh a user's access_token by initiating a redirect to the
getConnect
action in the controller.
Create User Logic
If you want to customize the logic used to create a user during the social login flow, modify the create_user
key in the config file.
'create_user' => function ($data) {
$user = new User;
$user->email = array_get($data, 'email');
$user->password = Hash::make(Str::random());
$user->location = array_get($data, 'location'); // Only passed by certain providers.
$user->save();
return $user->id;
},
Note: Make sure to return a numeric primary key when finished.
Note: The information passed in the
$data
parameter is the data returned from thefetch_user_info
functions for each provider in the config file.
Provider User Information
To customize which data you want to retrieve from a social provider account, modify the fetch_user_info
key for each provider in the config file.
'fetch_user_info' => function ($service) {
$result = json_decode($service->request('account/verify_credentials.json'), true);
return array(
'id' => array_get($result, 'id'),
'email' => null,
'first_name' => array_get(explode(' ', array_get($result, 'name')), 0),
'last_name' => array_get(explode(' ', array_get($result, 'name')), 1)
'location' => array_get($result, 'location'),
);
},
Note: This function also allows you to normalize the user data returned by each of the social providers by mapping their fields to fields you want to store in your user record.
New User Validation
You can configure the social login flow to validate the user information returned by the social provider. This way you can ensure that all of the data you require for a new user is properly obtained and in the correct format.
To customize the validation rules, modify the user_validation
key in the config file.
'user_validation' => array(
'email' => 'required|email',
'first_name' => 'required',
'location' => 'required',
),
Note: You may also declare a closure function to create and return a Validator instance for greater flexibility.
Social Buttons
This package provides some convenient css that allows you to create nice social buttons. It is built for use with the Twitter Bootstrap and Font Awesome frameworks.
Publish The Assets
Publish the public assets for this package.
$ php artisan asset:publish mmanos/laravel-social
Include The Assets
{{ HTML::style('/packages/mmanos/laravel-social/css/socialbuttons.css') }}
Building Buttons
<a href="{{ route('social-login', array('twitter')) }}" class="btn btn-social btn-twitter">
<i class="fa fa-twitter"></i> Log in with Twitter
</a>
<a href="{{ route('social-login', array('twitter')) }}" class="btn btn-social-icon btn-twitter">
<i class="fa fa-twitter"></i>
</a>
See here for a list of supported class names.