laravel-connect/README.md

# 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:

```bash
composer update bluesquare/laravel-connect
```

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

```bash
BCONNECT_CLIENT_ID=your_client_id
BCONNECT_CLIENT_SECRET=your_client_secret
BCONNECT_REDIRECT=http://localhost:8000/connect/callback
```

### 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:

```blade
<x-connect-button/>
```

Make sure that the `password` column of users table is nullable.

#### 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 models must use `HasConnectSync` trait. This trait allows you to customize the syncing behavior.

You also need to add this column to your synced tables:

```
$table->unsignedBigInteger('connect_resource_id')->unique();
```

_You can customize this column name and the syncing behavior in your model. Take a look at `HasConnectSync`._

Finally, use this command to sync everything:

```bash
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:

```bash
php artisan vendor:publish
```