Update README.md

README.md

@@ -1,213 +1,217 @@
 # laravel-connect
 
-The Bluesquare Connect package allows you to use its OAuth server and sync its resources.
+Ce package permet d'utiliser [Bluesquare Connect](https://connect.bluesquare.io) comme méthode d'authentification grâce au protocole OAuth 2.0.
 
 ## Installation
 
-Update your `composer.json`:
+Mettre à jour les sources de `composer.json` avec :
 
 ```
-"repositories": [
-    {
-        "type": "vcs",
-        "url": "https://git.bluesquare.io/bluesquare/laravel-connect"
-    }
-]
+composer config repositories.connect vcs https://git.bluesquare.io/bluesquare/laravel-connect.git -n
 ```
 
-Install the package:
+Puis installer le package :
 
 ```bash
-composer require bluesquare/laravel-connect "1.2"
+composer require bluesquare/laravel-connect "2.3"
 ```
 
-Finally, update your `.env` with your client's credentials:
+Mettre à jour le `.env` avec les identifiants du client OAuth généré sur [Bluesquare Connect](https://connect.bluesquare.io) :
 
 ```bash
 BCONNECT_CLIENT_ID=your_client_id
 BCONNECT_CLIENT_SECRET=your_client_secret
-BCONNECT_REDIRECT=http://localhost:8000/connect/callback
+BCONNECT_REDIRECT="${APP_URL}/connect/callback"
 ```
 
-### Sign in with Bluesquare Connect
+Et optionnellement :
 
-Follow there instructions to add Bluesquare Connect's authentication to your app.
-
-Update your `routes/web.php`:
+```bash
+# URL du serveur OAuth
+BCONNECT_URL=https://connect.bluesquare.io
 
+# Données demandées (scopes)
+BCONNECT_USER_SCOPES=profile
 ```
+
+Il est possible de modifier d'autres comportements, à savoir :
+- Model utilisateur utilisé (par défaut `App\Models\User`)
+- URL de connexion via Bluesquare Connect (par défaut `/connect/authorize`)
+- Remember me : garder la session active post-connexion (par défaut `true`)
+
+Pour cela, il suffit de modifier le fichier `config/bconnect.php` généré via la commande `php artisan vendor:publish`.
+
+### Configuration minimale de `User`
+
+À moins d'utiliser le trait `HasConnectData` (voir ci-dessous), il faut s'assurer que toutes les colonnes autres que `email` sont `nullable` dans la table `users` (y compris `password`).
+La colonne `email` est alors utilisée comme identifiant de référence par Bluesquare Connect.
+
+### Connexion
+
+Pour activer la connexion via Bluesquare Connect, il faut mettre à jour `web.php` en y ajoutant :
+
+```php
+use Bluesquare\Connect\Facades\Connect;
+
 Connect::routes();
 ```
 
-Add the "Sign in with Bluesquare Connect" button in your blade login page:
+Si Blade est utilisé, un bouton "Connexion via Bluesquare Connect" peut être ajouté ainsi :
 
 ```blade
 <x-connect-button/>
 ```
 
-Make sure that the `password` column of users table is nullable.
+Sinon il suffit de rediriger vers `/connect/authorize` pour déclencher le flux.
 
-#### Keep user tokens (optional)
+### Configuration personnalisée de `User`
 
-First, make sure that your model implements `HasConnectTokens` trait.
+Le trait `HasConnectData` permet d'exploiter au maximum les données fournies par Bluesquare Connect. Notamment :
+- Définir quelle colonne sert d'identifiant unique (par défaut `connect_id`) avec `$connectIdentifier` ;
+- Définir quelles données sont à injectées dans le Model à la connexion, avec `$connectFillable`
 
-Then, add the following columns to your table:
+Pour utiliser l'identifiant par défaut, il convient d'ajouter cette colonne à `User` :
 
+```php
+$table->string('connect_id')->nullable();
 ```
+
+Ou alors, et pour revenir à l'utilisation de `email` comme identifiant :
+
+```php
+use HasConnectData;
+
+protected $connectIdentifier = 'email';
+```
+
+Ensuite, pour injecter automatiquement les données fournies par Bluesquare Connect (liste indicative ci-dessous) :
+
+```php
+protected $connectFillable = [
+    'name',
+    'email'
+];
+```
+
+Il est possible de mapper les colonnes avec des noms différents et des valeurs par defaut, voire même d'injecter dans plusieurs colonnes, comme ceci :
+
+```php
+protected $connectIdentifier = ['connect_id' => 'oauth_id'];
+
+protected $connectFillable = [
+    'name' => 'fullname|Anonymous',
+    'firstname' => ['firstname', 'nickname'],
+    'email' => 'email_address',
+    'group' => 'role|user'
+];
+```
+
+Un hook est disponible pour un post-traitement des données Connect (après création / mise à jour de l'utilisateur) ce qui peut être utile pour mettre à jour des relations :
+
+```php
+use HasConnectData;
+
+public function postFillConnectData(array $data)
+{
+    // Exemple
+    $this->roles()->sync(
+        Role::whereIn('name', $data['groups'])->pluck('id')
+    );
+}
+```
+
+## Synchronisation des données _(optionnel)_
+
+Par défaut, les données des utilisateurs sont mises à jour à chaque nouvelle connexion. 
+Cependant, deux méthodes peuvent être utilisées pour conserver les données de tous les utilisateurs à jour sans reconnexion.
+
+### 1. Synchronisation passive
+
+Le trait `HasConnectTokens` permet de conserver les tokens OAuth pour une utilisation future (par exemple, pour synchroniser les utilisateurs périodiquement).
+
+Avant tout, il faut ajouter ces colonnes dans la table `users` :
+
+```php
 $table->text('connect_access_token')->nullable();
 $table->text('connect_refresh_token')->nullable();
-$table->dateTime('connect_expires_at')->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:
+Il est ensuite possible de mettre à jour les utilisateurs avec cette commande :
 
 ```bash
 php artisan connect:sync
 ```
 
-#### Live updates (optional)
+Mais aussi de seulement mettre à jour les tokens avant expiration avec cette commande :
 
-First, configure a webhook on Bluesquare Connect :
+```bash
+php artisan connect:refresh
+```
+
+Il est conseillé d'appeler ces commandes périodiquement via une tâche CRON dans `Console/Kernel.php`.
+
+### 2. Synchronisation active (webhook)
+
+Avant tout, il est requis de créer une `App` liée au client utilisé sur Bluesquare Connect, et d'en activer le webhook.
+
+Ensuite, pour pouvoir utiliser le webhook, il faut ajouter ceci à `routes/api.php`:
+
+```
+use Bluesquare\Connect\Facades\Connect;
+
+Connect::apiRoutes();
+```
+
+Cela va permettre à Bluesquare Connect d'appeler cette URL à chaque modification d'un utilisateur :
 
 ```
 https://your-app.com/api/connect/webhook
 ```
 
-Then, update your `routes/api.php`:
+Pour terminer, il suffit d'ajouter le trait `HasConnectWebhook` à `User`.
 
-```
-Connect::apiRoutes();
-```
+#### Configurer le comportement du webhook
 
-## Advanced usage
+Par défaut, le webhook se comporte ainsi :
+- Lorsqu'un utilisateur est créé, il est inséré dans `users` comme à la première connexion ;
+- Lorsqu'un utilisateur est mis à jour, il est modifié comme à chaque connexion / synchronisation ;
+- Lorsqu'un utilisateur est supprimé, deux cas se présentent :
+  - si `User` implémente `SoftDeletes`, alors le webhook fait appel à `$user->delete()` ;
+  - si `SoftDeletes` est absent, alors la session utilisateur est simplement expirée en repassant `remember_token` à `null`.
+- Si l'utilisateur est restauré, deux cas se présentent :
+    - si `User` implémente `SoftDeletes` et que l'utilisateur est bien présent en base de données, alors le webhook fait appel à `$user->restore()` ;
+    - si `SoftDeletes` est absent ou que l'utilisateur n'existe pas, alors on recréé l'utilisateur (s'il existe, il est simplement mis à jour).
 
-### OAuth (sign in)
+Il est recommandé de personnaliser le cas de la suppression en ajoutant la fonction suivante à `User.php` :
 
-#### Authorization
-
-Redirect to Bluesquare Connect authorization page:
-
-```
-public function authorize(Connect $connect)
+```php
+public function onConnectDelete(array $data)
 {
-    return $connect->redirect($optional_custom_state);
+    // Optionnel : avec cette fonction on met à jour une dernière fois l'utilisateur
+    $this->onConnectUpdate($data);
+
+    //...supprimer l'utilisateur comme souhaité...
 }
 ```
 
-#### Authorization callback
+Les autres cas peuvent être personnalisés avec ces différentes fonctions :
 
-Auto: check state, login and redirect
-
-```
-public function callback(Request $request, Connect $connect)
-{
-    return $connect->loginFromCallback($request, $optional_redirect_to);
-}
+```php
+public function onConnectCreate(array $data);
+public function onConnectUpdate(array $data);
+public function onConnectRestore(array $data);
 ```
 
-Manual: check state
+## Données fournies par Bluesquare Connect
 
-```
-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
-```
+- `id` et `connect_id` : identifiant unique de l'utilisateur
+- `email` : adresse e-mail
+- `name` : nom complet
+- `firstname` et `nickname` : prénom
+- `lastname` : nom de famille
+- `avatar`, `picture` et `profile_picture` : URL de la photo de profil
+- `company` : entreprise
+- `job` : mêtier exercé dans l'entreprise
+- `group` : rôle principal (les groupes sont personnalisées pour chaque App sur Bluesquare Connect)
+- `groups` : tableau contenant tous les rôles associés à l'utilisateur

src/Commands/Sync.php

@@ -4,6 +4,7 @@ namespace Bluesquare\Connect\Commands;
 
 use Bluesquare\Connect\Connect;
 use Bluesquare\Connect\ConnectException;
+use Bluesquare\Connect\Traits\HasConnectData;
 use Bluesquare\Connect\Traits\HasConnectTokens;
 use Illuminate\Console\Command;
 
@@ -32,6 +33,10 @@ class Sync extends Command
                         $data = $connect->getUserData($model->connect_access_token);
                         $connect->updateUserData($model, $data);
                         $model->save();
+
+                        if (in_array(HasConnectData::class, class_uses($model))) {
+                            $model->postFillConnectData($data);
+                        }
                     }
                 }
                 catch (\Exception $exception) {

src/Connect.php

@@ -6,6 +6,7 @@ use Bluesquare\Connect\Traits\HasConnectData;
 use Bluesquare\Connect\Traits\HasConnectTokens;
 use Bluesquare\Connect\Traits\HasConnectWebhook;
 use GuzzleHttp\Client;
+use Illuminate\Contracts\Foundation\Application;
 use Illuminate\Http\Request;
 use Illuminate\Routing\Router;
 use Illuminate\Support\Facades\Log;
@@ -17,7 +18,7 @@ class Connect
 {
     protected $app;
 
-    public function __construct($app)
+    public function __construct(Application $app)
     {
         $this->app = $app;
     }
@@ -94,7 +95,7 @@ class Connect
 
         $url = $this->getUrl() . '/oauth/authorize?' . $query;
 
-        return redirect()->to($url);
+        return redirect($url);
     }
 
     public function checkState(Request $request)
@@ -209,7 +210,7 @@ class Connect
             $model = $this->resolveUser($data, $hasSoftDeletes);
 
             if ($model->exists()) {
-                if ($hasSoftDeletes) {
+                if ($hasSoftDeletes && $model->trashed()) {
                     $event = 'restore';
                 } else {
                     $event = 'update';
@@ -223,6 +224,10 @@ class Connect
         } else {
             $this->updateUserData($model, $data);
             $model->save();
+
+            if (in_array(HasConnectData::class, class_uses($model))) {
+                $model->postFillConnectData($data);
+            }
         }
 
         return $model;

src/Traits/HasConnectData.php

@@ -44,4 +44,9 @@ trait HasConnectData
         foreach ($touched as $model)
             $model->save();
     }
+
+    public function postFillConnectData(array $data)
+    {
+        // Intended for post-processing / relationship handling
+    }
 }

src/Traits/HasConnectWebhook.php

@@ -18,6 +18,10 @@ trait HasConnectWebhook
         }
 
         $this->save();
+
+        if (in_array(HasConnectData::class, class_uses(self::class))) {
+            $this->postFillConnectData($data);
+        }
     }
 
     public function onConnectDelete(array $data)