From 116cb045beb48f5b1d9d5e3ea740642990648d77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Samuel=20=C5=A0tancl?= Date: Fri, 4 Oct 2019 23:34:19 +0200 Subject: [PATCH] 1.x -> 2.x upgrade guide --- docs/navigation.php | 4 +- docs/source/v2/configuration.blade.md | 2 +- docs/source/v2/custom-db-connections.blade.md | 10 ++++ .../{event-system.blade.md => hooks.blade.md} | 14 ++--- docs/source/v2/tenancy-bootstrappers.blade.md | 2 +- docs/source/v2/upgrading.blade.md | 54 +++++++++++++++++++ 6 files changed, 77 insertions(+), 9 deletions(-) create mode 100644 docs/source/v2/custom-db-connections.blade.md rename docs/source/v2/{event-system.blade.md => hooks.blade.md} (76%) create mode 100644 docs/source/v2/upgrading.blade.md diff --git a/docs/navigation.php b/docs/navigation.php index 1677136..44263d1 100644 --- a/docs/navigation.php +++ b/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', diff --git a/docs/source/v2/configuration.blade.md b/docs/source/v2/configuration.blade.md index 30f18ad..e646082 100644 --- a/docs/source/v2/configuration.blade.md +++ b/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} diff --git a/docs/source/v2/custom-db-connections.blade.md b/docs/source/v2/custom-db-connections.blade.md new file mode 100644 index 0000000..1033263 --- /dev/null +++ b/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. diff --git a/docs/source/v2/event-system.blade.md b/docs/source/v2/hooks.blade.md similarity index 76% rename from docs/source/v2/event-system.blade.md rename to docs/source/v2/hooks.blade.md index d94e199..1d21814 100644 --- a/docs/source/v2/event-system.blade.md +++ b/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(, 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(, 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']); }); ``` diff --git a/docs/source/v2/tenancy-bootstrappers.blade.md b/docs/source/v2/tenancy-bootstrappers.blade.md index b60f752..2c09cef 100644 --- a/docs/source/v2/tenancy-bootstrappers.blade.md +++ b/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. diff --git a/docs/source/v2/upgrading.blade.md b/docs/source/v2/upgrading.blade.md new file mode 100644 index 0000000..1f440e7 --- /dev/null +++ b/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') }}) \ No newline at end of file