3.x redesign

source/docs/v3/features/cross-domain-redirect.blade.md

@@ -0,0 +1,15 @@
+---
+title: Cross-domain redirect
+extends: _layouts.documentation
+section: content
+---
+
+# Cross-domain redirect
+
+To enable this feature, uncomment the `Stancl\Tenancy\Features\CrossDomainRedirect::class` line in your `tenancy.features` config.
+
+Sometimes you may want to redirect the user to a specific route on a different domain (than the current one). Let's say you want to redirect a tenant to the `home` path on their domain after they sign up:
+
+```php
+return redirect()->route('home')->domain($domain);
+```

source/docs/v3/features/telescope-tags.blade.md

@@ -0,0 +1,9 @@
+---
+title: Telescope tags
+extends: _layouts.documentation
+section: content
+---
+
+# Telescope tags
+
+TODO

source/docs/v3/features/tenant-config.blade.md

@@ -0,0 +1,49 @@
+---
+title: Tenant-specific config
+extends: _layouts.documentation
+section: content
+---
+
+# Tenant config
+
+It's likely you will need to use tenant-specific config in your application. That config could be API keys, things like "products per page" and many other things.
+
+You could just use the the tenant model to get these values, but you may still want to use Laravel's `config()` because of:
+
+- separation of concerns — if you just write tenancy implementation-agnostic `config('shop.products_per_page')`, you will have a much better time changing tenancy implementations
+- default values — you may want to use the tenant storage only to override values in your config file
+
+## **Enabling the feature**
+
+Uncomment the following line in your `tenancy.features` config:
+
+```php
+// Stancl\Tenancy\Features\TenantConfig::class,
+```
+
+## **Configuring the mappings**
+
+This feature maps keys in the tenant storage to config keys based on the `$storageToConfigMap` public property.
+
+For example, if your `$storageToConfigMap` looked like this:
+
+```php
+\Stancl\Tenancy\Features\TenantConfig::$storageToConfigMap = [
+    'paypal_api_key' => 'services.paypal.api_key',
+],
+```
+
+the value of `paypal_api_key` in tenant model would be copied to the `services.paypal.api_key` config when tenancy is initialized.
+
+## Mapping the value to multiple config keys
+
+Sometimes you may want to copy the value to multiple config keys. To do that, specify the config keys as an array:
+
+```php
+\Stancl\Tenancy\Features\TenantConfig::$storageToConfigMap = [
+    'locale' => [
+        'app.locale',
+        'locales.default',
+    ],
+],
+```

source/docs/v3/features/universal-routes.blade.md

@@ -0,0 +1,37 @@
+---
+title: Universal routes
+extends: _layouts.documentation
+section: content
+---
+
+# Universal Routes
+
+Sometimes, you may want to use the exact same **route action** both in the central application and the tenant application. Note the emphasis on route **action** — you may use the same **path** with different actions in central & tenant routes, whereas this section covers using the same **route and action**.
+
+Generally, try to avoid these use cases as much as possible and prefer duplicating the code. Using the same controller and model for users in central & tenant apps will break down once you need slightly different behavior — e.g. different views returned by controllers, different behavior on models, etc.
+
+First, enable the `UniversalRoutes` feature by uncommenting the following line in your `tenancy.features` config:
+
+```php
+Stancl\Tenancy\Features\UniversalRoutes::class,
+```
+
+Next, go to your `app/Http/Kernel.php` file and add the following middleware group:
+
+```php
+'universal' => [],
+```
+
+We will use this middleware group as a "flag" on the route, to mark it as a universal route. We don't need any actual middleware inside the group.
+
+Then, create a route like this:
+
+```php
+Route::get('/foo', function () {
+    // ...
+})->middleware(['universal', InitializeTenancyByDomain::class]);
+```
+
+And the route will work in both central and tenant applications. Should a tenant be found, tenancy will be initialized. Otherwise, the central context will be used.
+
+If you're using a different middleware, look at the `UniversalRoutes` feature source code and change the public static property accordingly.

source/docs/v3/features/user-impersonation.blade.md

@@ -0,0 +1,117 @@
+---
+title: User impersonation
+extends: _layouts.documentation
+section: content
+---
+
+# User impersonation
+
+This package comes with a feature that lets you impersonate users inside tenant databases. This feature works with **any identification method** and **any auth guard** — even if you use multiple.
+
+## How it works
+
+You generate an impersonation token an store it in the central database, in the `tenant_user_impersonation_tokens` table.
+
+Each record in the table holds the following data:
+
+- The token value (128 character string)
+- The tenant's id
+- The user's id
+- The name of the auth guard
+- The URL to redirect to after the impersonation takes place
+
+You visit an impersonation route that you create — though little work is needed on your side, your route will mostly just call a method provided by the feature. This route is a **tenant route**, meaning it's on the tenant domain if you use domain identification, or prefixed with the tenant id if you use path identification.
+
+This route checks tries to find a record in that table based on the token, and if it's valid it authenticates you with the stored user id against the auth guard and redirects you to the stored URL.
+
+If the impersonation succeeds, the token is deleted from the database.
+
+All tokens expire after 60 seconds by default, and this TTL can be customized — see the section at the very bottom.
+
+## Enabling the feature
+
+To enable this feature, go to your `config/tenancy.php` file and make sure the following class is in your `features` part of the config:
+
+```jsx
+Stancl\Tenancy\Features\UserImpersonation::class,
+```
+
+Next, publish the migration for creating the table with impersonation tokens:
+
+```jsx
+php artisan vendor:publish --tag=impersonation-migrations
+```
+
+And finally, run the migration:
+
+```jsx
+php artisan migrate
+```
+
+## Usage
+
+First, you need to create a tenant route that looks like this:
+
+```jsx
+use Stancl\Tenancy\Features\UserImpersonation;
+
+// We're in your tenant routes!
+
+Route::get('/impersonate/{token}', function ($token) {
+    return UserImpersonation::makeResponse($token);
+});
+
+// Of course use a controller in a production app and not a Closure route.
+// Closure routes cannot be cached.
+```
+
+Note that the route path or name are completely up to you. The only logic that the package does is generating tokens, verifying tokens, and doing the impersonated user log in.
+
+Then, to use impersonation in your app, generate a token like this:
+
+```jsx
+// Let's say we want to be redirected to the dashboard
+// after we're logged in as the impersonated user.
+$redirectUrl = '/dashboard';
+
+$token = tenancy()->impersonate($tenant, $user->id, $redirectUrl);
+```
+
+And redirect the user (or, presumably an "admin") to the route you created.
+
+### Domain identification
+
+```jsx
+// Note: This is not part of the package, it's up to you to implement
+// a concept of "primary domains" if you need them. Or maybe you use
+// one domain per tenant. The package lets you do anything you want.
+$domain = $tenant->primary_domain;
+return redirect("https://$domain/impersonate/$token");
+```
+
+### Path identification
+
+```jsx
+// Make sure you use the correct prefix for your routes.
+return redirect("{$tenant->id}/impersonate/$token");
+```
+
+And that's it. The user will be redirected to your impersonation route, logged in as the impersonated user, and finally redirected to your redirect URL.
+
+### Custom auth guards
+
+If you're using multiple auth guards, you may want to specify what auth guard the impersonation logic should use.
+
+To do this, simply pass the auth guard name as the fourth argument to the `impersonate()` method. So to expand on our example above:
+
+```jsx
+tenancy()->impersonate($tenant, $user->id, $redirectUrl, 'jwt');
+```
+
+## Customization
+
+You may customize the TTL of impersonation tokens by setting the following static property to the amount of seconds you want to use:
+
+```jsx
+Stancl\Tenancy\Features\UserImpersonation::$ttl = 120; // 2 minutes
+```