README

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 and onerror 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 the fetch_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.

mmanos / laravel-social

Maintainers

Details