diff --git a/docs/navigation.php b/docs/navigation.php index 8ff376a..a468d02 100644 --- a/docs/navigation.php +++ b/docs/navigation.php @@ -65,7 +65,9 @@ return [ 'url' => 'usage', 'children' => [ 'Creating Tenants' => 'creating-tenants', + 'Tenant Migrations'=> 'tenant-migrations', 'Tenant Routes' => 'tenant-routes', + 'Tenant Objects' => 'tenant', // todo rename route? 'Tenant Storage' => 'tenant-storage', 'Tenant Manager' => 'tenant-manager', 'Console Commands' => 'console-commands', diff --git a/docs/source/_layouts/master.blade.php b/docs/source/_layouts/master.blade.php index d09b1c5..c592a66 100644 --- a/docs/source/_layouts/master.blade.php +++ b/docs/source/_layouts/master.blade.php @@ -81,7 +81,7 @@ @yield('body') - + @stack('scripts') diff --git a/docs/source/_layouts/master_v2.blade.php b/docs/source/_layouts/master_v2.blade.php index eeab3b6..a21ea15 100644 --- a/docs/source/_layouts/master_v2.blade.php +++ b/docs/source/_layouts/master_v2.blade.php @@ -81,7 +81,7 @@ @yield('body') - + @stack('scripts') diff --git a/docs/source/v2/configuration.blade.md b/docs/source/v2/configuration.blade.md index 23156e5..367bc8d 100644 --- a/docs/source/v2/configuration.blade.md +++ b/docs/source/v2/configuration.blade.md @@ -96,25 +96,25 @@ 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. -### `migrate_after_creation` +### `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-database-after-tenant-deletion} Delete the tenant's database after deleting the tenant. - Default: `false` -### `queue_database_creation` +### `queue_database_creation` {#queue-database-creation} - Default: `false` -### `queue_database_deletion` +### `queue_database_deletion` {#queue-database-deletion} - Default: `false` -### `unique_id_generator` +### `unique_id_generator` {#unique-id-generator} The class used to generate a random tenant ID (when no ID is supplied during the tenant creation process). diff --git a/docs/source/v2/creating-tenants.blade.md b/docs/source/v2/creating-tenants.blade.md index 2a3c83c..91b5ce8 100644 --- a/docs/source/v2/creating-tenants.blade.md +++ b/docs/source/v2/creating-tenants.blade.md @@ -1,6 +1,6 @@ --- title: Creating Tenants -description: Creating tenants.. +description: Creating tenants extends: _layouts.documentation_v2 section: content --- @@ -12,14 +12,19 @@ section: content To create a tenant, you can use ```php -Tenant::new()->withDomains(['tenant1.yourapp.com'])->withData(['plan' => 'free'])->save(); +use Stancl\Tenancy\Tenant; + +Tenant::new() + ->withDomains(['tenant1.yourapp.com', 'tenant1.com']) + ->withData(['plan' => 'free']) + ->save(); ``` > Tip: All domains under `.localhost` are routed to 127.0.0.1 on most operating systems. This is useful for development. The `withDomains()` and `withData()` methods are optional. -You can also create a tenant using the `Tenant::create` method: +You can also create a tenant using a single method: `Tenant::create`: ```php $domains = ['tenant1.myapp.com', 'tenant1.com']; @@ -28,4 +33,6 @@ Tenant::create($domains, [ ]); ``` -> Note: Creating a tenant doesn't run [migrations](https://stancl-tenancy.netlify.com/docs/console-commands/#migrate) automatically. You have to do that yourself. \ No newline at end of file +`Tenant::create()` works with both `Stancl\Tenancy\Tenant` and the facade, `\Tenant`. + +> Note: By default, creating a tenant doesn't run [migrations]({{ $page->link('tenant-migrations' )}}) automatically. You may change this behavior using the `migrate_after_creation` [configuration]({{ $page->link('configuration#migrate-after-creation') }}). \ No newline at end of file diff --git a/docs/source/v2/tenant-manager.blade.md b/docs/source/v2/tenant-manager.blade.md index 4b9f5db..b518f47 100644 --- a/docs/source/v2/tenant-manager.blade.md +++ b/docs/source/v2/tenant-manager.blade.md @@ -1,43 +1,29 @@ --- title: Tenant Manager -description: Tenant Manager. +description: Tenant Manager extends: _layouts.documentation_v2 section: content --- # Tenant Manager {#tenant-manager} -This page documents a couple of other `TenantManager` methods you may find useful. +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()` is an alias for `getTenantById()`. You may use the second argument to specify the key(s) as a string/array. - ```php ->>> tenant()->find('dbe0b330-1a6e-11e9-b4c3-354da4b4f339'); -=> [ - "id" => "dbe0b330-1a6e-11e9-b4c3-354da4b4f339", - "domain" => "localhost", - "foo" => "bar", - ] ->>> tenant()->find('dbe0b330-1a6e-11e9-b4c3-354da4b4f339', 'foo'); -=> [ - "foo" => "bar", - ] ->>> tenant()->getTenantById('dbe0b330-1a6e-11e9-b4c3-354da4b4f339', ['foo', 'domain']); -=> [ - "foo" => "bar", - "domain" => "localhost", - ] -``` - -### Getting tenant ID by domain - -```php ->>> tenant()->getTenantIdByDomain('localhost'); -=> "b3ce3f90-1a88-11e9-a6b0-038c6337ae50" ->>> tenant()->getIdByDomain('localhost'); -=> "b3ce3f90-1a88-11e9-a6b0-038c6337ae50" +>>> \Tenancy::find('b07aa3b0-dc68-11e9-9352-9159b2055c42') +=> Stancl\Tenancy\Tenant {#3099 + +data: [ + "id" => "b07aa3b0-dc68-11e9-9352-9159b2055c42", + "plan" => "free", + ], + +domains: [ + "foo.localhost", + ], + } ``` ### Finding tenant by domain @@ -45,25 +31,29 @@ This page documents a couple of other `TenantManager` methods you may find usefu You may use the second argument to specify the key(s) as a string/array. ```php ->>> tenant()->findByDomain('localhost'); -=> [ - "id" => "b3ce3f90-1a88-11e9-a6b0-038c6337ae50", - "domain" => "localhost", - ] +>>> tenancy()->findByDomain('bar.localhost') +=> Stancl\Tenancy\Tenant {#3091 + +data: [ + "id" => "b38b2bd0-dc68-11e9-adfc-ede94ab3b264", + ], + +domains: [ + "bar.localhost", + ], + } ``` -### Accessing the array +### Getting the current tenant -You can access the public array tenant of TenantManager like this: +One more way to get the current [tenant]({{ $page->link('tenant') }}) is to call `getTenant()` on `TenantManager`: ```php -tenancy()->tenant +tenancy()->getTenant() ``` -which is an array. If you want to get the value of a specific key from the array, you can use one of the helpers the key on the tenant array as an argument. +If you want to get the value of a specific key from the array, you can an argument with the key. ```php -tenant('id'); // Does the same thing as tenancy()->getTenant('id') +tenancy()->getTenant('id'); // Does the same thing as tenant('id') ``` ### Getting all tenants @@ -71,24 +61,36 @@ tenant('id'); // Does the same thing as tenancy()->getTenant('id') This method returns a collection of arrays. ```php ->>> tenant()->all(); -=> Illuminate\Support\Collection {#2980 +>>> tenancy()->all() +=> Illuminate\Support\Collection {#3080 all: [ - [ - "id" => "32e20780-1a88-11e9-a051-4b6489a7edac", - "domain" => "localhost", - ], - [ - "id" => "49670df0-1a87-11e9-b7ba-cf5353777957", - "domain" => "dev.localhost", - ], + Stancl\Tenancy\Tenant {#3076 + +data: [ + "id" => "b07aa3b0-dc68-11e9-9352-9159b2055c42", + ], + +domains: [ + "foo.localhost", + ], + }, + Stancl\Tenancy\Tenant {#3075 + +data: [ + "id" => "b38b2bd0-dc68-11e9-adfc-ede94ab3b264", + ], + +domains: [ + "bar.localhost", + ], + }, ], } ->>> tenant()->all()->pluck('domain'); -=> Illuminate\Support\Collection {#2983 +>>> tenancy()->all()->pluck('domains') +=> Illuminate\Support\Collection {#3108 all: [ - "localhost", - "dev.localhost", + [ + "foo.localhost", + ], + [ + "bar.localhost", + ], ], } ``` @@ -96,17 +98,25 @@ This method returns a collection of arrays. ### Deleting a tenant ```php ->>> tenant()->delete('dbe0b330-1a6e-11e9-b4c3-354da4b4f339'); -=> true ->>> tenant()->delete(tenant()->getTenantIdByDomain('dev.localhost')); -=> true ->>> tenant()->delete(tenant()->findByDomain('localhost')['uuid']); +>>> $tenant = tenancy()->findByDomain('foo.localhost'); +=> Stancl\Tenancy\Tenant {#3119 + +data: [ + "id" => "b07aa3b0-dc68-11e9-9352-9159b2055c42", + "plan" => "free", + ], + +domains: [ + "foo.localhost", + ], + } +>>> $tenant->delete(); => 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()` ```php ->>> tenant()->getDatabaseName(tenant()->findByDomain('laravel.localhost')) +>>> $tenant->getDatabaseName() => "tenant67412a60-1c01-11e9-a9e9-f799baa56fd9" -``` \ No newline at end of file +``` + +If you want tenant databases to be deleted automatically, you may use the [`delete_database_after_tenant_deletion` configuration]({{ $page->link('configuration#delete-database-after-tenant-deletion') }}) \ No newline at end of file diff --git a/docs/source/v2/tenant-migrations.md b/docs/source/v2/tenant-migrations.md new file mode 100644 index 0000000..500ef99 --- /dev/null +++ b/docs/source/v2/tenant-migrations.md @@ -0,0 +1,30 @@ +--- +title: Tenant Migrations +description: Tenant Migrations +extends: _layouts.documentation_v2 +section: content +--- + +# Tenant Migrations {#tenant-migrations} + +You can run tenant migrations using the `php artisan tenants:migrate` command. + +You may specify the tenant(s) using the `--tenants` option. + +``` +php artisan tenants:migrate --tenants=8075a580-1cb8-11e9-8822-49c5d8f8ff23 +``` + +> Note: Tenant migrations must be located in `database/migrations/tenant`. + +You can run migrations from outside the command line as well. To run migrations for a tenant in your code, use `Artisan::call()`: + +```php +$tenant = \Tenant::create('tenant1.localhost'); + +\Artisan::call('tenants:migrate', [ + '--tenants' => [$tenant->id]; +]); +``` + +You may also [configure]({{ $page->link('configuration#migrate-after-creation') }}) the package to run migrations automatically, after creating tenants. diff --git a/docs/source/v2/tenant-routes.blade.md b/docs/source/v2/tenant-routes.blade.md index 73a586c..a30f6fe 100644 --- a/docs/source/v2/tenant-routes.blade.md +++ b/docs/source/v2/tenant-routes.blade.md @@ -11,7 +11,7 @@ Routes within `routes/tenant.php` will have the `web` middleware group and the ` Just like `routes/web.php`, these routes use the `App\Http\Controllers` namespace. -> If a tenant cannot be identified, anexception will be thrown. If you want to change this behavior (to a redirect, for example) read the [Middleware Configuration]({{ $page->link('middleware-configuration') }}) page. +> 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. ## Exempt routes {#exempt-routes} diff --git a/docs/source/v2/tenant-storage.blade.md b/docs/source/v2/tenant-storage.blade.md index ebb9bb3..779d6f0 100644 --- a/docs/source/v2/tenant-storage.blade.md +++ b/docs/source/v2/tenant-storage.blade.md @@ -7,30 +7,29 @@ section: content # Tenant Storage {#tenant-storage} -Tenant storage is where tenants' ids and domains are stored. You can store things like the tenant's plan, subscription information, and tenant-specific application configuration in tenant storage. You can use these functions: +Tenant storage is where tenants' ids and domains are stored. You can store things like the tenant's plan, subscription information, and tenant-specific application configuration in tenant storage. You may use these functions on `Tenant` objects: ```php -get (string|array $key, string $id = null) // $id defaults to the current tenant's id -put (string|array $key, mixed $value = null, string $id = null) // if $key is array, make sure $value is null +get (string|array $key) +put (string|array $key, mixed $value = null) // if $key is array, make sure $value is null ``` To put something into the tenant storage, you can use `put()` or `set()`. ```php -tenancy()->put($key, $value); -tenancy()->set($key, $value); // alias for put() -tenancy()->put($key, $value, $id); -tenancy()->put(['key1' => 'value1', 'key2' => 'value2']); -tenancy()->put(['key1' => 'value1', 'key2' => 'value2'], null, $id); +$tenant->put($key, $value); +$tenant->set($key, $value); // alias for put() +$tenant->put(['key1' => 'value1', 'key2' => 'value2']); ``` To get something from the storage, you can use `get()`: ```php -tenancy()->get($key); -tenancy()->get($key, $id); -tenancy()->get(['key1', 'key2']); +tenant()->get($key); +tenant()->get(['key1', 'key2']); ``` -> Note: `tenancy()->get(['key1', 'key2'])` returns an array with values only +> In this example, we're calling the methods on the current tenant — `tenant()`. + +> Note: `get(['key1', 'key2'])` returns an associative array. Note that $key has to be a string or an array with string keys. The value(s) can be of any data type. Example with arrays: diff --git a/docs/source/v2/tenant.md b/docs/source/v2/tenant.md new file mode 100644 index 0000000..e4d5291 --- /dev/null +++ b/docs/source/v2/tenant.md @@ -0,0 +1,10 @@ +--- +title: Tenant Objects +description: Tenant Objects +extends: _layouts.documentation_v2 +section: content +--- + +# Tenant Objects {#tenant-objects} + +todo \ No newline at end of file diff --git a/docs/source/v2/usage.blade.md b/docs/source/v2/usage.blade.md index c700e39..54a277c 100644 --- a/docs/source/v2/usage.blade.md +++ b/docs/source/v2/usage.blade.md @@ -9,8 +9,8 @@ section: content This chapter describes usage of the package. That includes creating tenants, deleting tenants, storing data in the tenant storage. -This package comes with two helpers - `tenancy()` and `tenant()`. `tenancy()` returns an instance of `TenantManager` and should be primarily used only for `tenancy()->all()`, but for legacy reasons it can be used to create tenants. - -You can pass an argument to the helper function to get a value out of the tenant storage. `tenant('plan')` is identical to [`tenant()->get('plan')`]({{ $page->link('tenant-storage') }}). +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.