[6.x] Document Credential Storages and Refactored Auth User Store to support different guards (foxbytehq#122)

Author: JamesFreeman

docs/credential-storage.md

@@ -1,26 +1,77 @@
-## Credential Storage
+# Credential Storage
 
+There are currently five credential storage options available:
+
+1. ** File Store ** (default) - Stores the credentials in a JSON file on the default disk.
+2. ** Cache Store ** - Stores the credentials in the cache.
+3. ** Model Store ** - Stores the credentials against a predefined model.
+4. ** Authenticated User Store ** - Stores the credentials against the authenticated user.
+5. ** Array Store ** - Stores the credentials in an array.
+
+## Changing the default storage
+
+If your using a default storage you can change the `xero.credential_store` config key to point to the new implementation.
+
+## File Store
 Credentials are stored in a JSON file using the default disk on the Laravel Filesystem, with visibility set to private. This allows credential sharing across multiple servers using a shared disk such as S3, regardless of which server conducted the OAuth flow.
 
 To use a different disk, change the `xero.credential_disk` config item to another disk defined in `config/filesystem.php`.
 
-You can switch out the credential store (e.g. for your own `UserStore` if you wanted to store
-the credentials against your user) in one of two ways:
+## Cache Store
+
+Credentials are stored in the cache, this is useful for applications that do not have a shared disk.
+
+## Model Store
+
+Credentials are stored against a predefined model, this is useful for applications that have a settings model.
+
+For the package to know which model you want to use, you will need to call the following method:
+
+```php
+use Webfox\Xero\Xero;
+
+Xero::useModelStore(Settings::class);
+```
+
+By default, the package will use the `xero_credentials` field, Should you need to rename this field, you can do so by calling:
+
+```php
+use Webfox\Xero\Xero;
+
+Xero::useAttributeOnModelStore('my_custom_field');
+```
+
+## Authenticated User Store
+
+Credentials are stored against the authenticated user. By default, the package will use the `xero_credentials` field on the Users table. 
 
-1. If it's a simple store and Laravel can automatically resolve your bindings, simply change the `xero.credential_store` config
-   key to point to your new implementation.
-2. If it requires more advanced logic (e.g. using the current user to retrieve the credentials) then you can rebind this
-   in your `AppServiceProvider` or a Middleware
-   e.g.
+Should you need to rename this field, you can do so by calling: 
 
 ```php
-$this->app->bind(OauthCredentialManager::class, function(Application $app) {
-    return new UserStorageProvider(
-        \Auth::user(), // Storage Mechanism 
-        $app->make('session.store'), // Used for storing/retrieving oauth 2 "state" for redirects
-        $app->make(\Webfox\Xero\Oauth2Provider::class) // Used for getting redirect url and refreshing token
-    );
-});
+use Webfox\Xero\Xero;
+
+Xero::useAttributeOnModelStore('my_custom_field');
 ```
 
-An example UserStorageProvider [can be found here](https://github.com/webfox/laravel-xero-oauth2/issues/45#issuecomment-757552563)
+Should you need to change the authentication guard, you can do so by calling:
+```php
+use Webfox\Xero\Xero;
+
+Xero::setDefaultAuthGuard('admin');
+```
+
+## Array Store
+
+Credentials are stored in an array, this is useful for testing purposes only. Once the application is restarted, the credentials will be lost.
+
+## Creating your own Storage Manager
+
+You can create your own storage manager by implementing the `OauthCredentialManager` interface, it is suggested that you extend the `BaseCredentialManager` class.
+
+You will need to implement the following methods:
+
+1. `exists()` - Returns a boolean indicating if the credentials exist.
+2. `store(AccessTokenInterface $token, array $tenants = null)` - Creates/Updates the credentials.
+3. `data(string $key = null)` - Returns the stored credentials (it is recommended you check the credentials exists, if not throw the `XeroCredentialsNotFound` exception).
+
+Once this has been completed, you should point `xero.credential_store` to your new implementation.