From abbed1c0959dca01eb38bc804b3b2500f76d2b22 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samuel=20=C5=A0tancl?= <samuel.stancl@gmail.com>
Date: Sun, 22 Sep 2019 17:27:51 +0200
Subject: [PATCH] Tenant routes 2.x

---
 docs/source/v2/configuration.blade.md |  4 ++++
 docs/source/v2/tenant-routes.blade.md | 27 ++++++++++++++++++++++-----
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/docs/source/v2/configuration.blade.md b/docs/source/v2/configuration.blade.md
index 367bc8d..c81ce27 100644
--- a/docs/source/v2/configuration.blade.md
+++ b/docs/source/v2/configuration.blade.md
@@ -96,6 +96,10 @@ The aliases are used by the [event system]({{ $page->link('event-system') }})
 
 Features are similar to bootstrappers, but they are executed regardless of whether tenancy has been initialized or not. Their purpose is to provide additional functionality that is not necessary for the package to work. Things like easy redirects to tenant domains, tags in Telescope, etc.
 
+### `home_url` {#home-url}
+
+When a user tries to visit a non-tenant route on a tenant domain, the `PreventAccessFromTenantDomains` middleware will return a redirect to this url.
+
 ### `migrate_after_creation` {#migrate-after-creation}
 
 Run migrations after creating a tenant.
diff --git a/docs/source/v2/tenant-routes.blade.md b/docs/source/v2/tenant-routes.blade.md
index a30f6fe..c706fa8 100644
--- a/docs/source/v2/tenant-routes.blade.md
+++ b/docs/source/v2/tenant-routes.blade.md
@@ -9,7 +9,7 @@ section: content
 
 Routes within `routes/tenant.php` will have the `web` middleware group and the `IntializeTenancy` middleware automatically applied on them. This middleware attempts to identify the tenant based on the current hostname. Once the tenant is identified, the database connection, cache, filesystem root paths and, optionally, Redis connection, will be switched.
 
-Just like `routes/web.php`, these routes use the `App\Http\Controllers` namespace.
+Just like `routes/web.php`, these routes use the `App\Http\Controllers` namespace (you can [configure this]({{ $page->link('configuration#tenant-route-namespace') }}))
 
 > If a tenant cannot be identified, an exception will be thrown. If you want to change this behavior (to a redirect, for example) read the [Middleware Configuration]({{ $page->link('middleware-configuration') }}) page.
 
@@ -17,7 +17,7 @@ Just like `routes/web.php`, these routes use the `App\Http\Controllers` namespac
 
 Routes outside the `routes/tenant.php` file will not have the tenancy middleware automatically applied on them. You can apply this middleware manually, though.
 
-If you want some of your, say, API routes to be multi-tenant, simply wrap them in a Route group with this middleware:
+If you want some of your, say, API routes to be multi-tenant, wrap them in a Route group with this middleware:
 
 ```php
 use Stancl\Tenancy\Middleware\InitializeTenancy;
@@ -27,8 +27,25 @@ Route::middleware(InitializeTenancy::class)->group(function () {
 });
 ```
 
-## Using the same routes for tenant and non-tenant parts of the application {#using-the-same-routes-for-tenant-and-non-tenant-parts-of-the-application}
+and apply the `Stancl\Tenancy\Middleware\PreventAccessFromTenantDomains` middleware on the *entire* group:
 
-The `Stancl\Tenancy\Middleware\PreventAccessFromTenantDomains` middleware makes sure 404 is returned when a user attempts to visit a web route on a tenant (non-exempt) domain.
+```php
+// app/Http/Kernel.php
+protected $middlewareGroups = [
+    // ...
+    'api' => [
+        \Stancl\Tenancy\Middleware\PreventAccessFromTenantDomains::class,
+        // ...
+    ]
+];
+```
 
-The install command applies this middleware to the `web` group. If you want to do this for another route group, add this middleware manually to that group. You can do this in `app/Http/Kernel.php`.
\ No newline at end of file
+## The `PreventAccess...` middleware {#prevent-access-middleware}
+
+**You cannot have conflicting routes in `web.php` and `tenant.php`**. It would break `php artisan route:list` and route caching.
+
+Since you probably want cleaner URLs on your non-tenant part of the application (landing page, etc), prefix your tenant routes with something like `/app`.
+
+The `Stancl\Tenancy\Middleware\PreventAccessFromTenantDomains` middleware prevents access to non-tenant routes from tenant domains by returning a redirect to the tenant app's home page ([`tenancy.home_url']({{ $page->link('configuration#home-url') }})). Conversely, it returns a 404 when a user attempts to visit a tenant route on a web (exempt) domain.
+
+The install command applies this middleware to the `web` group. If you want apply it for another route group, add this middleware manually to that group. You can do this in `app/Http/Kernel.php`.
\ No newline at end of file