1.x -> 2.x upgrade guide

docs/navigation.php

@@ -52,6 +52,7 @@ return [
         'GitHub'       => 'https://github.com/stancl/tenancy',
     ],
     'v2' => [
+        'Upgrading from 1.x' => 'upgrading',
         'Getting Started' => [
             'url'      => 'getting-started',
             'children' => [
@@ -79,9 +80,10 @@ return [
                 'Tenant Config'              => 'tenant-config',
                 'Middleware Configuration'   => 'middleware-configuration',
                 'Custom Database Names'      => 'custom-database-names',
+                'Custom DB Connections'      => 'custom-db-connections',
                 'Filesystem Tenancy'         => 'filesystem-tenancy',
                 'Jobs & Queues'              => 'jobs-queues',
-                'Event System'               => 'event-system',
+                'Hooks / Events'             => 'hooks',
                 'Tenancy Initialization'     => 'tenancy-initialization',
                 'Tenancy Bootstrappers'      => 'tenancy-bootstrappers',
                 'Application Testing'        => 'application-testing',

docs/source/v2/configuration.blade.md

@@ -88,7 +88,7 @@ This config is an array. The key is the alias and the value is the full class na
 'cache' => Stancl\Tenancy\TenancyBootstrappers\CacheTenancyBootstrapper::class,
 ```
 
-The aliases are used by the [event system]({{ $page->link('event-system') }})
+The aliases are used by the [event system]({{ $page->link('hooks') }})
 
 ### `features` {#bootstrappers}
 

docs/source/v2/custom-db-connections.blade.md

@@ -0,0 +1,10 @@
+---
+title: Custom Database Connections
+description: Custom Database Connections
+extends: _layouts.documentation
+section: content
+---
+
+# Custom Database Connections {#custom-database-names}
+
+To set a specific database connection for a tenant, set the `_tenancy_db_connection` key in the tenant's storage. The connection's database name will be still replaced by the tenant's database name. You can [customize that]({{ $page->link('custom-database-names') }}) too.

docs/source/v2/hooks.blade.md

@@ -1,11 +1,11 @@
 ---
-title: The Event System
-description: The Event System..
+title: Hooks / The Event System
+description: Hooks / The Event System
 extends: _layouts.documentation
 section: content
 ---
 
-# The Event System
+# Hooks / The Event System
 
 You can use event hooks to change the behavior of the tenancy bootstrapping and tenancy ending processes.
 
@@ -17,9 +17,11 @@ The following events are available:
 
 ### Tenant-specific database connection example {#tenant-specific-database-connection-example}
 
-You can hook into these events using `Tenancy::eventListener(<eventName>, function () {})`:
+> Note: Tenant-specific DB connections can now be achieved using a first-class feature: [Custom DB connections]({{ $page->link('custom-db-connections') }})
+
+You can hook into these events using `Tenancy::hook(<eventName>, function () {})`:
 ```php
-\Tenancy::eventListener('bootstrapping', function ($tenantManager) {
+\Tenancy::hook('bootstrapping', function ($tenantManager) {
     if ($tenantManager->tenant['id'] === 'someID') {
         config(['database.connections.someDatabaseConnection' => $tenantManager->tenant['databaseConnection']]);
         $tenantManager->database->useConnection('someDatabaseConnection');
@@ -43,7 +45,7 @@ The following actions can be prevented:
 
 Another common use case for events is tenant-specific config:
 ```php
-\Tenancy::eventListener('bootstrapped', function ($tenantManager) {
+\Tenancy::hook('bootstrapped', function ($tenantManager) {
     config(['some.api.key' => $tenantManager->tenant['api_key']);
 });
 ```

docs/source/v2/tenancy-bootstrappers.blade.md

@@ -15,4 +15,4 @@ When tenancy is [initialized]({{ $page->link('tenancy-initialization') }}), the
 
 Conversely, when tenancy is ended, the `end()` method is called.
 
-In the [`tenancy.bootstrappers` configuration]( {{ $page->link('configuration#bootstrappers') }} ), bootstrappers have an alias configured (e.g. `database`) that is used by [events]({{ $page->link('event-system') }}) to say which bootstrappers are prevented.
+In the [`tenancy.bootstrappers` configuration]( {{ $page->link('configuration#bootstrappers') }} ), bootstrappers have an alias configured (e.g. `database`) that is used by [events]({{ $page->link('hooks') }}) to say which bootstrappers are prevented.

docs/source/v2/upgrading.blade.md

@@ -0,0 +1,54 @@
+---
+title: Upgrading
+description: Upgrading
+extends: _layouts.documentation
+section: content
+---
+
+# Upgrading from 1.x {#upgrading}
+
+The 2.0.0 release is essentialy a ~60% rewrite, with 3,187 additions and 1,896 deletions (lines of code). Version 2 introduces Laravel 6 support and drops Laravel 5.8 support.
+
+This guide attempts to cover the main changes that were made to the package. The rewrite was mainly:
+- an internal thing: much better code quality means much better maintainability and much more features in the future :)
+- to provide a nicer API for working with tenants
+
+Even though new syntax was one of the main goals, the rewrite was made with backwards compatibility in mind, so many old methods still work.
+
+If you're coming from 1.x, it's recommended to read (or at least skim through) the entire documentation again.
+
+## Main changes
+
+- `Tenant` objects are now used, instead of arrays, to represent tenants. See the [Tenants]({{ $page->link('tenants') }}) page.
+- Tenants can now have multiple domains, so a new `domains` table is used by the DB storage driver.
+- The `uuid` property on tenants is now `id`.
+- `tenancy()` helper now returns an instance of `TenantManager` while the `tenant()` helper returns an instance of the current `Tenant`. If no `Tenant` has been identified, `null` is returned. Same with the `Tenancy` and `Tenant` facades.
+- Event listeners/hooks have a new syntax: `Tenancy::eventListener('bootstrapping', function () {})`
+- The tenancy bootstrapping logic has been extracted into separate classes, such as `DatabaseTenancyBootstrapper`, `CacheTenancyBootstrapper` etc.
+- A concept of `Feature`s was introduced. They're classes that provide additional functionality - functionality that is not necessary to bootstrap tenancy.
+- predis support was dropped. Laravel will drop predis support in 7.x.
+- There is new syntax for [creating]({{ $page->link('creating-tenants') }}) and [interacting]({{ $page->link('tenants') }}) with tenants, be sure to read those documentation pages again.
+- The config was changed *a lot*, so you should publish and configure it again.
+    You can publish the configuration like this:
+    ```none
+    php artisan vendor:publish --provider='Stancl\Tenancy\TenancyServiceProvider' --tag=config
+    ```
+
+## DB storage driver
+- The `uuid` column in the `tenants` table was renamed to `id`. The `domain` column was dropped.
+- A new migration was added to create the `domains` table. **The old migration was renamed**, so if you publish migrations again, be sure to delete the old migration, to avoid creating the table twice.
+    You can publish migrations like this:
+    ```none
+    php artisan vendor:publish --provider='Stancl\Tenancy\TenancyServiceProvider' --tag=migrations
+    ```
+
+## Redis storage driver
+
+- The `uuid` keys are now `id`.
+- The `domain` key was dropped.
+- The `_tenancy_domains` key is used to store an array of domains that belong to the tenant.
+
+## New Features
+
+- [Tenant Config]({{ $page->link('tenant-config') }})
+- [Migrate Fresh]({{ $page->link('commands#migrate-fresh') }})