Introduction

Sentry Social makes authenticating your users through social networks & third-party OAuth providers an absolute breeze.

The package requires PHP 5.3+ and comes bundled with a Laravel 4 Facade and a Service Provider to simplify the optional framework integration and follows the FIG standard PSR-0 to ensure a high level of interoperability between shared PHP code and is fully unit-tested.

Have a read through the Installation Guide and on how to Integrate it with Laravel 4.

Features

• Ability to authenticate through a number of pre-configured OAuth 1 and OAuth 2 services as well as adding an infinite number of custom OAuth 1 and OAuth 2 services.
• Automatic user association and registering as well as logging in.
• Simplistic API with ability to customize behavior as needed.

Oauth 1 Services

• FitBit
• Twitter

Oauth 2 Services

• bitly
• Facebook
• Foursquare
• GitHub
• Google
• LinkedIn
• Microsoft
• SoundCloud
• Yammer

Installation

The best and easiest way to install the Sentry Social package is with Composer.

Preparation

Open your composer.json file and add the following to the require array:

"cartalyst/sentry-social": "2.1.*"

Add the following lines after the require array on your composer.json file:

"repositories": [
    {
        "type": "composer",
        "url": "https://packages.cartalyst.com"
    }
]

Note: Make sure that after the required changes your composer.json file is valid by running composer validate.

Install the dependencies

Run Composer to install or update the new requirement.

php composer install

or

php composer update

Now you are able to require the vendor/autoload.php file to autoload the package.

Integration

Laravel 4

The Sentry Social package has optional support for Laravel 4 and it comes bundled with a Service Provider and a Facade for easy integration.

After installing the package, open your Laravel config file located at app/config/app.php and add the following lines.

In the $providers array add the following service provider for this package.

'Cartalyst\SentrySocial\SentrySocialServiceProvider',

In the $aliases array add the following facade for this package.

'SentrySocial' => 'Cartalyst\SentrySocial\Facades\Laravel\SentrySocial',

Configuration

After installing, you can publish the package configuration file into your application by running the following command on your terminal:

php artisan config:publish cartalyst/sentry-social

This will publish the config file to app/config/packages/cartalyst/sentry-social/config.php where you can modify the package configuration.

Native

Instantiate Sentry Social

$manager = new Cartalyst\SentrySocial\Manager($instanceOfSentry);

Usage

Using Sentry Social is easy. Once you have configured it, you simply need to call the make() method to retrieve a "Service" instance. From there, you may request tokens, authenticate etc. Sounds complicated? It's not.

For the examples, we'll use the Laravel Facade, however the same methods may be called on a $sentrySocial variable, non-statically.

Making a Service

Making a service is very easy:

// Make the "facebook" service
$service = SentrySocial::make('facebook', 'http://url-which-you-would-like-to/redirect-do');

Using a Service

Once you have made a service, you need to redirect the user to the "authorization URI". This is the URI where they will login to their service (e.g. Facebook) and it will ask for permission to access their basic data.

$service = SentrySocial::make('facebook', 'http://url-which-you-would-like-to/redirect-do');

// Let's redirect the user to authorize with Facebook
return Redirect::to((string) $service->getAuthorizationUri());

Authenticating the User

Once the user has authorized your application, they'll get redirected to the URL which you specified when you made the service, in this case http://url-which-you-would-like-to/redirect-do. We then want to use the code which has been passed back as $_GET parameter and authenticate the user. This is the magic which ties the service login with a Sentry login. It will create non-existent users and link existing ones. A user may be linked to multiple services as well:

$service = SentrySocial::make('facebook', 'http://url-which-you-would-like-to/redirect-do');

if ($code = Input::get('code'))
{
    if ($user = SentrySocial::authenticate($service, $code))
    {
        var_dump($user);

        // Additionally, the user will be logged in, so this
        // is the same:
        // var_dump(Sentry::getUser());

        // Continue with your application's workflow, the user is logged in!
    }
}

Laravel 4

In Laravel 4, we've added a controller which handles the registration flow for you. Feel free to use it, extend it or replace it, but it should get you started on your way to authenticating using Sentry Social.

// To use it, in app/routes.php
Route::controller('oauth', 'Cartalyst\SentrySocial\Controllers\OAuthController');

// To extend it, make a class which extends Cartalyst\SentrySocial\Controllers\OAuthController
Route::controller('oauth', 'MyOAuthController');