From 667467ddc4dc0fc73c06ef3ddbe4502cb2842830 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Samuel=20=C5=A0tancl?= Date: Sat, 21 Sep 2019 23:57:14 +0200 Subject: [PATCH] 2.x config --- docs/source/v2/configuration.blade.md | 67 ++++++++++++++++++- ...e-between-this-package-and-others.blade.md | 2 +- docs/source/v2/getting-started.blade.md | 3 +- docs/source/v2/installation.blade.md | 15 +++-- docs/source/v2/storage-drivers.blade.md | 14 ++-- 5 files changed, 82 insertions(+), 19 deletions(-) diff --git a/docs/source/v2/configuration.blade.md b/docs/source/v2/configuration.blade.md index 249263c..23156e5 100644 --- a/docs/source/v2/configuration.blade.md +++ b/docs/source/v2/configuration.blade.md @@ -19,6 +19,19 @@ Available storage drivers: - `Stancl\Tenancy\StorageDrivers\RedisStorageDriver` - `Stancl\Tenancy\StorageDrivers\Database\DatabaseStorageDriver` +#### db {#db-storage-driver} + +- `data_column` - the name of column that holds the tenant's data in a single JSON string +- `custom_columns` - list of keys that shouldn't be put into the data column, but into their own column +- `connection` - what database connection should be used to store tenant data (`null` means the default connection) +- `table_names` - the table names used by each the models that come with the storage driver + +> Note: Don't use the models directly. You're supposed to use [storage]({{ $page->link('tenant-storage') }}) methods on `Tenant` objects. + +#### redis {#redis-db-driver} + +- `connection` - what Redis connection should be used to store tenant data + ### `tenant_route_namespace` {#tenant-route-namespace} Controller namespace used for routes in `routes/tenant.php`. The default value is the same as the namespace for `web.php` routes. @@ -53,4 +66,56 @@ The root of each disk listed in `tenancy.filesystem.disks` will be suffixed with For disks listed in `root_override`, the root will be that string with `%storage_path%` replaced by `storage_path()` *after* tenancy has been initialized. All other disks will be simply suffixed with `tenancy.filesystem.suffix_base` + the tenant id. -Read more about this on the [Filesystem Tenancy]({{ $page->link('filesystem-tenancy') }}) page. \ No newline at end of file +Read more about this on the [Filesystem Tenancy]({{ $page->link('filesystem-tenancy') }}) page. + +### `database_managers` {#database_managers} + +Tenant database managers handle the creation & deletion of tenant databases. This configuration array maps the database driver name to the `TenantDatabaseManager`, e.g.: + +```php +'mysql' => 'Stancl\Tenancy\TenantDatabaseManagers\MySQLDatabaseManager' +``` + +### `database_manager_connections` {#database_maanger_connections} + +Connections used by TenantDatabaseManagers. They tell, for example, that the manager for the `mysql` driver (`MySQLDatabaseManager`) should use the `mysql` connection. You may want to change this if your connection is named differently, e.g. a MySQL connection named `central`. + +### `bootstrappers` {#bootstrappers} + +These are the classes that do the magic. When tenancy is initialized, TenancyBootstrappers are executed, making Laravel tenant-aware. + +This config is an array. The key is the alias and the value is the full class name. + +```php +'cache' => 'Stancl\Tenancy\TenancyBootstrappers\CacheTenancyBootstrapper', +``` + +The aliases are used by the [event system]({{ $page->link('event-system') }}) + +### `features` {#bootstrappers} + +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. + +### `migrate_after_creation` + +Run migrations after creating a tenant. +- Default: `false` + +### `delete_database_after_tenant_deletion` + +Delete the tenant's database after deleting the tenant. +- Default: `false` + +### `queue_database_creation` + +- Default: `false` + +### `queue_database_deletion` + +- Default: `false` + +### `unique_id_generator` + +The class used to generate a random tenant ID (when no ID is supplied during the tenant creation process). + +- Default: `Stancl\Tenancy\UUIDGenerator` diff --git a/docs/source/v2/difference-between-this-package-and-others.blade.md b/docs/source/v2/difference-between-this-package-and-others.blade.md index 03f2bb8..cc91b2e 100644 --- a/docs/source/v2/difference-between-this-package-and-others.blade.md +++ b/docs/source/v2/difference-between-this-package-and-others.blade.md @@ -11,7 +11,7 @@ A frequently asked question is the difference between this package and [tenancy/ Packages like tenancy/multi-tenant and tenancy/tenancy give you an API for making your application multi-tenant. They give you a tenant DB connection, traits to apply on your models, a guide on creating your own tenant-aware cache, etc. -This package makes your application multi-tenant automatically and attempts to make you not have to change (m)any things in your code. +This package (stancl/tenancy) makes your application multi-tenant automatically and attempts to make you not have to change any things in your code. The philosophy behind this approach is that you should write your app, not tenancy boilerplate. ## Which one should you use? diff --git a/docs/source/v2/getting-started.blade.md b/docs/source/v2/getting-started.blade.md index 958db29..2600f1c 100644 --- a/docs/source/v2/getting-started.blade.md +++ b/docs/source/v2/getting-started.blade.md @@ -9,8 +9,6 @@ section: content [**stancl/tenancy**](https://github.com/stancl/tenancy) is a Laravel multi-database tenancy package. It makes your app multi-tenant in a way that requires no changes to the codebase. Instead of applying traits on models and replacing every single reference to cache by a reference to a tenant-aware cache, the package lets you write your app without thinking about tenancy. It handles tenancy automatically in the background. -> Note: Filesystem is the only thing that can be a little problematic. Be sure to read [that page]({{ $page->link('filesystem-tenancy') }}). - ## How does it work? {#how-does-it-work} A user visits `client1.yourapp.com`. The package identifies the tenant who this domain belongs to, and automatically does the following: @@ -18,6 +16,7 @@ A user visits `client1.yourapp.com`. The package identifies the tenant who this - replaces the default cache manager - switches Redis connection - changes filesystem root paths +- makes jobs automatically tenant-aware The benefits of this being taken care of by the package are: - separation of concerns: you should write your app, not tenancy implementations diff --git a/docs/source/v2/installation.blade.md b/docs/source/v2/installation.blade.md index e8e63a5..194b341 100644 --- a/docs/source/v2/installation.blade.md +++ b/docs/source/v2/installation.blade.md @@ -7,16 +7,18 @@ section: content # Installation {#getting-started} -Laravel 5.8 or higher is needed. +Laravel 6.0 or higher is needed. ### Require the package via composer First you need to require the package using composer: ``` -composer require stancl/tenancy +composer require stancl/tenancy:2.x-dev ``` +> **Note:** Be sure to `composer require stancl/tenancy` (without the `:2.x-dev`) once 2.0.0 is released. + ### Automatic installation {#automatic-installation} To install the package, simply run @@ -25,11 +27,9 @@ To install the package, simply run php artisan tenancy:install ``` -You will be asked if you want to store your data in Redis or a relational database. You can read more about this on the [Storage Drivers]({{ $page->link('storage-drivers') }}) page. - This will do all the steps listed in the [Manual installation](#manual-installation) section for you. -The only thing you have to do now is create a database/Redis connection. Read the [Storage Drivers]({{ $page->link('storage-drivers') }}) page for information about that. +You will be asked if you want to store your data in a relational database or Redis. Continue to the next page ([Storage Drivers]({{ $page->link('storage-drivers') }})) to know what that means. ### Manual installation {#manual-installation} @@ -37,10 +37,11 @@ If you prefer installing the package manually, you can do that too. It shouldn't #### Setting up middleware -Now open `app/Http/Kernel.php` and make the `InitializeTenancy` middleware top priority, so that it gets executed before anything else, making sure things like the database switch connections soon enough: +Now open `app/Http/Kernel.php` and make the package's middleware classes top priority, so that they get executed before anything else, making sure things like the database switch connections soon enough: ```php protected $middlewarePriority = [ + \Stancl\Tenancy\Middleware\PreventAccessFromTenantDomains::class, \Stancl\Tenancy\Middleware\InitializeTenancy::class, // ... ]; @@ -50,7 +51,7 @@ protected $middlewarePriority = [ The package lets you have tenant routes and "exempt" routes. Tenant routes are your application's routes. Exempt routes are routes exempt from tenancy — landing pages, sign up forms, and routes for managing tenants. -Routes in `routes/web.php` are exempt, whereas routes in `routes/tenant.php` have the `InitializeTenancy` middleware automatically applied on them. +Routes in `routes/web.php` are exempt, while routes in `routes/tenant.php` have the tenancy middleware automatically applied to them. So, to create tenant routes, put those routes in a new file called `routes/tenant.php`. diff --git a/docs/source/v2/storage-drivers.blade.md b/docs/source/v2/storage-drivers.blade.md index 00f3a0d..69576d6 100644 --- a/docs/source/v2/storage-drivers.blade.md +++ b/docs/source/v2/storage-drivers.blade.md @@ -7,7 +7,7 @@ section: content # Storage Drivers {#storage-drivers} -Storage drivers are used to store a list of all tenants, their domains and any extra information you store about your tenants (e.g. their plan). +Storage drivers are used to store a list of all tenants, their domains and any extra information you store about your tenants (their plan, API keys, etc). Currently, database and Redis storage drivers are available as part of the package. However, you can [write your own]({{ $page->link('writing-storage-drivers') }}) (and contribute ❤️) storage drivers. @@ -17,25 +17,23 @@ The database storage driver lets you store tenant information in a relational da The benefit of this storage driver is that you don't have to use both Redis and a database for your data. Also you don't have to do as much configuration. -To use this driver, you need to have a `tenants` table. You may also use a custom database connection. By default, `tenancy.storage.db.connection` is set to `central`, which means that the `central` database connection will be used to store tenants. This connection is not automatically created, so you'd have to create it manually. You can create database connections in the `config/database.php` file. +To use this driver, you need to have a `tenants` table and a `domains` table. You may also use a custom database connection. By default, `tenancy.storage.db.connection` is set to `null`, which means that the your default database connection will be used to store tenants. If you wish to use a different connection, you may create a it in the `config/database.php` file and set `tenancy.storage.db.connection` to the name of that connection. -If you'd like to use an existing connection, you can set this config to the name of the connection, e.g. `mysql`. - -To create the `tenants` table, you can use the migration that comes with this package. If you haven't published it during installation, publish it now: +To create the `tenants` and `domains` tables, you can use the migrations that come with this package. If you haven't published them during installation, publish them now: ``` php artisan vendor:publish --provider='Stancl\Tenancy\TenancyServiceProvider' --tag=migrations ``` By default, all of your data will be stored in the JSON column `data`. If you want to store some data in a dedicated column (to leverage indexing, for example), add the column to the migration and to `tenancy.custom_columns` config. -Finally, run the migration: +> If you have existing migrations related to your app in `database/migrations`, move them to `database/migrations/tenant`. You can read more about tenant migrations [here]({{ $page->link('console-commands/#migrate') }}). + +Finally, run the migrations: ``` php artisan migrate ``` > If you use a non-default connection, such as `central`, you have to specify which DB to migrate using the `--database` option. -> -> If you have existing migrations related to your app in `database/migrations`, move them to `database/migrations/tenant`. You can read more about tenant migrations [here]({{ $page->link('console-commands/#migrate') }}). ## Redis {#redis}