fixes; readme

README.md

@@ -1,42 +1,205 @@
-# 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"
+    "bluesquare/laravel-connect": "dev-master"
 }
-```
-
-
-```
 "repositories": [
-        {
-            "type": "vcs",
-            "url": "https://git.bluesquare.io/bluesquare/laravel-connect"
-        }
+    {
+        "type": "vcs",
+        "url": "https://git.bluesquare.io/bluesquare/laravel-connect"
+    }
 ]
 ```
 
-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
+```

src/Connect.php

@@ -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);
             }
         }
     }

src/Traits/HasConnectSync.php

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