Merge branch 'master' of github.com:stancl/tenancy-docs

docs/source/v2/configuration.blade.md

@@ -24,7 +24,7 @@ Available storage drivers:
 - `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
+- `table_names` - the table names used by 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.
 
@@ -50,14 +50,12 @@ You can set the suffix to `.sqlite` if you're using sqlite and want the files to
 
 If `tenancy.redis.tenancy` is set to true, connections listed in `tenancy.redis.prefixed_connections` will be prefixed with `config('tenancy.redis.prefix_base') . $id`.
 
-> Note: You need phpredis. Predis support will dropped by Laravel on version 7.
+> Note: You need phpredis. Predis support will dropped by Laravel in version 7.
 
 ### `cache` {#cache}
 
 The `CacheManager` instance that's resolved when you use the `Cache` or the `cache()` helper will be replaced by `Stancl\Tenancy\CacheManager`. This class automatically uses [tags](https://laravel.com/docs/master/cache#cache-tags). The tag will look like `config('tenancy.cache.tag_base') . $id`.
 
-If you need to store something in global, non-tenant cache, 
-
 ### `filesystem` {#filesystem}
 
 The `storage_path()` will be suffixed with a directory named `config('tenancy.filesystem.suffix_base') . $id`.
@@ -94,7 +92,7 @@ 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.
+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 beyond what is necessary for the package to work. Things like easy redirects to tenant domains, tags in Telescope, etc.
 
 ### `home_url` {#home-url}
 
@@ -103,11 +101,13 @@ When a user tries to visit a non-tenant route on a tenant domain, the `PreventAc
 ### `migrate_after_creation` {#migrate-after-creation}
 
 Run migrations after creating a tenant.
+
 - Default: `false`
 
 ### `delete_database_after_tenant_deletion` {#delete-database-after-tenant-deletion}
 
 Delete the tenant's database after deleting the tenant.
+
 - Default: `false`
 
 ### `queue_database_creation` {#queue-database-creation}

docs/source/v2/console-commands.blade.md

@@ -38,7 +38,7 @@ Similarly to [migrate](#migrate), these commands accept a `--tenants` option.
 
 ## Run {#run}
 
-You can use the tenants:run command to run your own commands for tenants.
+You can use the `tenants:run` command to run your own commands for tenants.
 
 If your command's signature were `email:send {--queue} {--subject=} {body}`, you would run this command like this:
 ```
@@ -61,4 +61,4 @@ You can delete specific tenants' cache by using the `--tags` option on `cache:cl
 php artisan cache:clear --tags=tenantdbe0b330-1a6e-11e9-b4c3-354da4b4f339
 ```
 
-The tag is `config('tenancy.cache.tag_base') . $id`.
+The tag is derived from `config('tenancy.cache.tag_base') . $id`.

docs/source/v2/custom-database-names.blade.md

@@ -7,9 +7,9 @@ section: content
 
 # Custom Database Names {#custom-database-names}
 
-To set the a database name for a tenant, use set `_tenancy_db_name` key in the tenant's storage.
+To set a specific database name for a tenant, set the `_tenancy_db_name` key in the tenant's storage.
 
-You should do this during the tenant creation process, to make sure the database is created with the right name:
+You should do this during the tenant creation process, to make sure the right database name is used during database creation.
 
 ```php
 use Stancl\Tenancy\Tenant;

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 (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.
+This package (stancl/tenancy) makes your application multi-tenant automatically and attempts to make you not have to change anything in your code. The philosophy behind this approach is that you should write your app, not tenancy boilerplate.
 
 Apart from saving you a ton of time, the benefit of going with the automatic approach (stancl/tenancy) is that you can adapt easily, since you're not bound to a specific implementation of multi-tenancy. [You can always change how tenancy is bootstrapped.]({{ $page->link('tenancy-bootstrappers') }})
 

docs/source/v2/event-system.blade.md

@@ -7,11 +7,11 @@ section: content
 
 # The Event System
 
-You can use event hooks to change the behavior of the tenancy boostrapping and tenancy ending processes.
+You can use event hooks to change the behavior of the tenancy bootstrapping and tenancy ending processes.
 
 The following events are available:
-- `boostrapping`
+- `bootstrapping`
-- `boostrapped`
+- `bootstrapped`
 - `ending`
 - `ended`
 

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

@@ -13,7 +13,16 @@ The `storage_path()` will be suffixed with a directory named `config('tenancy.fi
 
 The root of each disk listed in `tenancy.filesystem.disks` will be suffixed with `config('tenancy.filesystem.suffix_base') . $id`.
 
-**However, this alone would cause unwanted behavior.** It would work for S3 and similar disks, but for local disks, this would result in `/path_to_your_application/storage/app/tenant1e22e620-1cb8-11e9-93b6-8d1b78ac0bcd/`. That's not what we want. We want `/path_to_your_application/storage/tenant1e22e620-1cb8-11e9-93b6-8d1b78ac0bcd/app/`. Why? Because `storage_path()` returns `/path_to_your_application/storage/tenant1e22e620-1cb8-11e9-93b6-8d1b78ac0bcd/`, so `storage_path('app') means appending `app` to that.
+**However, this alone would cause unwanted behavior.** It would work for S3 and similar disks, but for local disks Laravel does its own suffixing. For local storage we need the second of these examples:
+```
+/path_to_your_application/storage/app/tenant1e22e620-1cb8-11e9-93b6-8d1b78ac0bcd/
+/path_to_your_application/storage/tenant1e22e620-1cb8-11e9-93b6-8d1b78ac0bcd/app/
+```
+Why? Because `storage_path()` returns:
+
+`/path_to_your_application/storage/tenant1e22e620-1cb8-11e9-93b6-8d1b78ac0bcd/`
+
+so Laravel's `storage_path('app')` means appending `app` to that.
 
 That's what the `root_override` section is for. `%storage_path%` gets replaced by `storage_path()` *after* tenancy has been initialized. The roots of disks listed in the `root_override` section of the config will be replaced accordingly. All other disks will be simply suffixed with `tenancy.filesystem.suffix_base` + the tenant id.
 
@@ -23,18 +32,18 @@ Since `storage_path()` will be suffixed, your folder structure will look like th
 
 If you write to these directories, you will need to create them after you create the tenant. See the docs for [PHP's mkdir](http://php.net/function.mkdir).
 
-Logs will be saved to `storage/logs` regardless of any changes to `storage_path()`.
+Logs will be saved to `storage/logs` regardless of any changes to `storage_path()`, and regardless of tenant.
 
 ## Assets {#assets}
 
-The `asset()` helper has two different paths of execution:
+Laravel's `asset()` helper has two different paths of execution:
 
 - If `config('app.asset_url')` has been set, it will simply append `tenant$id` to the end of the configured asset URL. This is useful if you use Laravel Vapor. Vapor sets the asset URL to something like `https://abcdefghijkl.cloudfrount.net/123-456-789`. That is the root for your assets. This package will append that with something like `tenant1e22e620-1cb8-11e9-93b6-8d1b78ac0bcd`.
 - If `config('app.asset_url')` is null, as it is by default, the helper will return a URL (`/tenancy/assets/...`) to a controller provided by this package. That controller returns a file response from `storage_path("app/public/$path")`. This means that you need to store your assets in the public directory.
 
 > Note: In 1.x, the `asset()` helper was not tenant-aware, and there was a `tenant_asset()` helper that followed the second option in the list above (a link to a controller). For backwards compatibility, that helper remains intact.
 
-> If you have some non-tenant-specific assets, you may use the `global_asset()` helper.
+> If you have some non-tenant-specific assets, you may use the pakage's `global_asset()` helper.
 
 Note that all tenant assets have to be in the `app/public/` subdirectory of the tenant's storage directory, as shown in the image above.
 

docs/source/v2/getting-started.blade.md

@@ -29,5 +29,6 @@ Multi-tenancy is the ability to provide your application to multiple customers (
 Multi-tenancy can be single-database and multi-database.
 
 **Single-database tenancy** means that your application uses only a single database. The way this is usually implemented is that instead of having the `id`, `title`, `user_id` and `body` columns in your `posts` table, you will also have a `tenant_id` column. This approach works until you need custom databases for your clients. It's also easy to implement, it basically boils down to having your models use a trait which adds a [global scope](https://laravel.com/docs/master/eloquent#global-scopes).
+Again, to be clear: This package does not provide single-database tenancy features.
 
 **Multi-database tenancy**, the type that this package provides, lets you use a separate database for each tenant. The benefits of this approach are scalability, compliance (some clients need to have the database on their server) and mitigation of risks such as showing the wrong tenant's data to a user. The downside is that this model is harder to implement, which is why this package exists.

docs/source/v2/global-stuff.blade.md

@@ -25,7 +25,7 @@ Create a new connection and use it like `DB::connection($connectionName)->table(
 
 ## Global Redis {#global-redis}
 
-Create a new connection, *don't* put it into `tenancy.redis.prefixed_connectoins`, and use it like `Redis::connection('foo')->get('bar')`
+Create a new connection, *don't* put it into `tenancy.redis.prefixed_connections`, and use it like `Redis::connection('foo')->get('bar')`
 
 ## Global Queues/Jobs {#global-queues-jobs}
 

docs/source/v2/storage-drivers.blade.md

@@ -17,14 +17,14 @@ 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 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.
+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 your app's default database connection will be used to store tenants. If you wish to use a different connection, you may create it in the `config/database.php` file and set `tenancy.storage.db.connection` to the name of that connection.
 
 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.
+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 the `tenancy.custom_columns` config.
 
 > 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('tenant-migrations') }}).
 
@@ -45,7 +45,7 @@ The benefit of this storage driver is its performance.
 
 Read the [Redis documentation page on persistence](https://redis.io/topics/persistence). You should definitely use AOF and if you want to be even more protected from data loss, you can use RDB **in conjunction with AOF**.
 
-If your cache driver is Redis and you don't want to use AOF with it, run two Redis instances. Otherwise, just make sure you use a different database (number) for tenancy and for anything else.
+If your cache driver is Redis and you don't want to use AOF with it, run two Redis instances. Otherwise, just make sure you use a different database (number) for tenancy and another for anything else.
 
 To use this driver, create a new Redis connection in the `database.redis` configuration (`config/database.php`) called `tenancy`.
 
@@ -57,3 +57,5 @@ To use this driver, create a new Redis connection in the `database.redis` config
     'database' => env('TENANCY_REDIS_DB', 3), // alternatively, different database number
 ],
 ```
+
+> Note: You need phpredis. Predis support will dropped by Laravel in version 7.

docs/source/v2/tenant-manager.blade.md

@@ -11,7 +11,7 @@ This page documents a couple of `TenantManager` methods you may find useful.
 
 To call methods on `TenantManager`, you may use the `tenancy()` helper or the `Tenancy` facade.
 
-### Finding tenant using id
+### Find tenant by id
 
 ```php
 >>> \Tenancy::find('b07aa3b0-dc68-11e9-9352-9159b2055c42')
@@ -26,9 +26,8 @@ To call methods on `TenantManager`, you may use the `tenancy()` helper or the `T
    }
 ```
 
-### Finding tenant by domain
+### Find tenant by domain
 
-You may use the second argument to specify the key(s) as a string/array.
 
 ```php
 >>> tenancy()->findByDomain('bar.localhost')
@@ -112,7 +111,9 @@ This method returns a collection of arrays.
 => true
 ```
 
-This doesn't delete the tenant's database. If you want to delete it, save the database name prior to deleting the tenant. You can get the database name using `getDatabaseName()`
+NOTE: This doesn't delete the tenant's database. 
+
+If you want to delete it, get the database name prior to deleting the tenant using `getDatabaseName()`.
 
 ```php
 >>> $tenant->getDatabaseName()

docs/source/v2/tenant-routes.blade.md

@@ -7,7 +7,9 @@ section: content
 
 # Tenant Routes {#tenant-routes}
 
-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.
+Routes within `routes/tenant.php` will have the `web` middleware group and the `IntializeTenancy` middleware automatically applied on them. 
+
+The `IntializeTenancy` 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 (you can [configure this]({{ $page->link('configuration#tenant-route-namespace') }}))
 
@@ -17,7 +19,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, wrap them in a Route group with this middleware:
+If you want certain routes (perhaps API routes) to be multi-tenant, wrap them in a Route group with this middleware:
 
 ```php
 use Stancl\Tenancy\Middleware\InitializeTenancy;
@@ -44,8 +46,8 @@ protected $middlewareGroups = [
 
 **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`.
+Suggestion: 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 `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`.
+The `tenancy: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`.

docs/source/v2/usage.blade.md

@@ -13,4 +13,4 @@ The package comes with two helpers - `tenancy()` and `tenant()`.
 - `tenancy()` returns an instance of [`TenantManager`]({{ $page->link('tenant-manager') }})
 - `tenant()` returns an instance of the current tenant, or null if no tenant hs been identified yet. You can pass an argument to this helper, to get a value from the tenant storage: `tenant('plan')` is identical to [`tenant()->get('plan')`]({{ $page->link('tenant-storage') }}).
 
-The package also comes with two facades. `Tenancy` -- for `TenantManager` -- and `Tenant` -- for the current `Tenant`, or null if no tenant has been identified yet.
+The package also comes with two facades. `Tenancy` -- for `TenantManager` -- and `Tenant` -- for the current `Tenant`.