laravel-connect/README.md

3.7 KiB

laravel-connect

The Bluesquare Connect package allows you to use its OAuth server and sync its resources.

Installation

Update your composer.json:

"require": {
    "bluesquare/laravel-connect": "dev-master"
}
"repositories": [
    {
        "type": "vcs",
        "url": "https://git.bluesquare.io/bluesquare/laravel-connect"
    }
]

Install the package:

composer update bluesquare/laravel-connect

Finally, update your .env with your client's credentials:

BCONNECT_CLIENT_ID=your_client_id
BCONNECT_CLIENT_SECRET=your_client_secret

Sign in with Bluesquare Connect

Follow there instructions to add Bluesquare Connect's authentication to your app.

Update your routes/web.php:

Connect::routes();

Add the "Sign in with Bluesquare Connect" button in your blade login page:

<x-connect-button/>

Keep user tokens (optional)

First, make sure that your model implements HasConnectTokens trait.

Then, add the following columns to your table:

$table->text('connect_access_token')->nullable();
$table->text('connect_refresh_token')->nullable();
$table->dateTime('connect_expires_at')->nullable();

Database syncing

Follow these instructions to sync your database with Bluesquare Connect.

In your AppServiceProvider, specify in the boot() function which entities you want to sync:

$connect->setSynchronized([
    Role::class,
    Company::class,
    Team::class,
    User::class,
    UserTeam::class
]);

Your entities must use HasConnectSync trait. This trait allows you to customize the syncing behavior.

Finally, use this command to sync everything:

php artisan connect:sync

Live updates (optional)

First, configure a webhook on Bluesquare Connect :

https://your-app.com/api/connect/webhook

Then, update your routes/api.php:

Connect::apiRoutes();

Advanced usage

OAuth (sign in)

Authorization

Redirect to Bluesquare Connect authorization page:

public function authorize(Connect $connect)
{
    return $connect->redirect($optional_custom_state);
}

Authorization callback

Auto: check state, login and redirect

public function callback(Request $request, Connect $connect)
{
    return $connect->loginFromCallback($request, $optional_redirect_to);
}

Manual: check state

public function callback(Request $request, Connect $connect)
{
    $valid = $connect->checkState($request);
    // ...
}

Tokens management

// Retrieve tokens from an authorization code
$connect_data = $connect->getAccessTokenFromAuthorizationCode($code);

// Retrieve tokens from a refresh token
$connect_data = $connect->getAccessTokenFromRefreshToken($connect_data['refresh_token']);

// With HasConnectTokens trait: get your local user tokens
$connect->getUserAccessToken($user);

User data

// Retrieve user data from an access token
$user_data = $connect->getUserData($connect_data['access_token']);

// Example: find the corresponding user in your database
$user = User::where('email', $user_data['email'])->first();

OAuth (client)

Token management

// Get an access token
$connect->getAccessToken();

// Delete the current access token from cache
$connect->deleteAccessToken();

API resources

// Fetch all users
$connect->getAll('User');

// Fetch an user
$connect->get('User', 1);

Syncing

// Sync everything
$optional_resource_types = ['User', ...];
$connect->syncAll($optional_resource_types);

// Sync a specific resource
$connect->sync('User', 1);

Webhook

// Handle a webhook request
$connect->handleWebhook($request);

Configuration

Publish our config file (config/bconnect.php) to customize the package configuration:

php artisan vendor:publish