fixes; readme

This commit is contained in:
Maxime Renou 2020-05-12 16:56:50 +02:00
parent 911045cdd2
commit a965ace522
3 changed files with 200 additions and 27 deletions

191
README.md
View File

@ -1,19 +1,15 @@
# laravel-bconnect
# laravel-connect
The Bluesquare Connect package allows you to use its OAuth server and sync its resources.
## Installation
First in your composer.json, add:
Update your `composer.json`:
```
"require": {
"bluesquare/laravel-connect": "dev-master"
}
```
```
"repositories": [
{
"type": "vcs",
@ -22,21 +18,188 @@ First in your composer.json, add:
]
```
Next, update your package:
Install the package:
```bash
composer update bluesquare/laravel-connect
```
Eventually, if you want to customize the config system:
```bash
php artisan vendor:publish
```
Finally, add in your `.env`:
Finally, update your `.env` with your client's credentials:
```bash
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:
```blade
<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:
```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
```

View File

@ -132,30 +132,35 @@ class Connect
return redirect()->to($url);
}
public function loginFromCallback(Request $request)
public function checkState(Request $request)
{
// State check
if (!session()->has('connect_states')) {
Log::debug("Missing session states");
return redirect('/');
return false;
}
$states = session()->get('connect_states');
if (!is_array($states)) {
Log::debug("Invalid session state");
return redirect('/');
return false;
}
if (!$request->has('state') || !in_array($request->state, $states)) {
Log::debug("Missing valid state in request");
return redirect('/');
return false;
}
unset($states[array_search($request->state, $states)]);
session()->put('connect_states', $states);
return true;
}
public function loginFromCallback(Request $request, $redirect_to = '/')
{
if (!$this->checkState($request))
return redirect('/');
// Code check
@ -184,7 +189,7 @@ class Connect
auth()->login($user, true);
return redirect('/');
return redirect($redirect_to);
}
public function getAccessTokenFromAuthorizationCode($code)
@ -355,7 +360,7 @@ class Connect
foreach ($model::all() as $item)
{
if (!in_array(intval($item->id), $identifiers))
$item->delete();
$model::onConnectResourceDoesNotExist($item);
}
}
}

View File

@ -33,4 +33,9 @@ trait HasConnectSync
$record = self::find($id);
return $record ? $record->delete() : false;
}
public static function onConnectResourceDoesNotExist($record)
{
return $record->delete();
}
}