laravel-connect/README.md

214 lines
4.0 KiB
Markdown

# laravel-connect
The Bluesquare Connect package allows you to use its OAuth server and sync its resources.
## Installation
Update your `composer.json`:
```
"repositories": [
{
"type": "vcs",
"url": "https://git.bluesquare.io/bluesquare/laravel-connect"
}
]
```
Install the package:
```bash
composer require bluesquare/laravel-connect "1.2"
```
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
```