Update docs for 2.x

docs/navigation.php

@@ -67,7 +67,6 @@ return [
                 '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',
@@ -76,6 +75,7 @@ return [
         'Digging Deeper' => [
             'url'      => 'digging-deeper',
             'children' => [
+                'Tenants'                    => 'tenants',
                 'Middleware Configuration'   => 'middleware-configuration',
                 'Custom Database Names'      => 'custom-database-names',
                 'Filesystem Tenancy'         => 'filesystem-tenancy',

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

@@ -7,15 +7,14 @@ section: content
 
 # Custom Database Names {#custom-database-names}
 
-If you want to specify the tenant's database name, set the `tenancy.database_name_key` configuration key to the name of the key that is used to specify the database name in the tenant storage. You must use a name that you won't use for storing other data, so it's recommended to avoid names like `database` and use names like `_stancl_tenancy_database_name` instead. Then just give the key a value during the tenant creation process:
+To set the a database name for a tenant, use set `_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:
 
 ```php
->>> tenancy()->create('example.com', [
-    '_stancl_tenancy_database_name' => 'example_com'
+use Stancl\Tenancy\Tenant;
+
+Tenant::create('example.com', [
+    '_tenancy_db_name' => 'example_com'
 ])
-=> [
-     "id" => "49670df0-1a87-11e9-b7ba-cf5353777957",
-     "domain" => "example.com",
-     "_stancl_tenancy_database_name" => "example_com",
-   ]
 ```

docs/source/v2/integrations.blade.md

@@ -10,3 +10,5 @@ section: content
 This package naturally integrates well with Laravel packages, since it does not rely on you explicitly specifying database connections.
 
 There are some exceptions, though. [Telescope integration]({{ $page->link('telescope') }}), for example, requires you to change the database connection in `config/telescope.php` to a non-default one, because the default connection is switched to the tenant connection. Some packages should use a central connection for data storage.
+
+> You may be thinking, why does the DB storage driver work with the default, central DB connection, but Telescope doesn't? It's because the DB storage driver intelligently uses the **original** default DB connection, if it has been changed.

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

@@ -26,7 +26,7 @@ php artisan vendor:publish --provider='Stancl\Tenancy\TenancyServiceProvider' --
 
 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.
 
-> 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') }}). <!-- todo2 custom page for tenant migrations -->
+> 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') }}).
 
 Finally, run the migrations:
 ```

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

@@ -44,7 +44,7 @@ You may use the second argument to specify the key(s) as a string/array.
 
 ### Getting the current tenant
 
-One more way to get the current [tenant]({{ $page->link('tenant') }}) is to call `getTenant()` on `TenantManager`:
+One more way to get the current [tenant]({{ $page->link('tenants') }}) is to call `getTenant()` on `TenantManager`:
 
 ```php
 tenancy()->getTenant()
@@ -53,7 +53,7 @@ tenancy()->getTenant()
 If you want to get the value of a specific key from the array, you can an argument with the key.
 
 ```php
-tenancy()->getTenant('id'); // Does the same thing as tenant('id')
+tenancy()->getTenant('id') // Does the same thing as tenant('id')
 ```
 
 ### Getting all tenants

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

@@ -20,6 +20,8 @@ $tenant->set($key, $value); // alias for put()
 $tenant->put(['key1' => 'value1', 'key2' => 'value2']);
 ```
 
+> **Note:** Don't start any keys with `_tenancy` unless instructed to by the docs. It is a reserved namespace used to store internal data by this package.
+
 To get something from the storage, you can use `get()`:
 
 ```php

docs/source/v2/tenant.md

@@ -1,10 +0,0 @@
----
-title: Tenant Objects
-description: Tenant Objects
-extends: _layouts.documentation_v2
-section: content
----
-
-# Tenant Objects {#tenant-objects}
-
-todo

docs/source/v2/tenants.blade.md

@@ -0,0 +1,99 @@
+---
+title: Tenants
+description: Tenants
+extends: _layouts.documentation_v2
+section: content
+---
+
+# Tenants {#tenants}
+
+This page covers the `Stancl\Tenancy\Tenant` object. Both [creating tenants]({{ $page->link('creating-tenants') }}) and interacting with the [tenant storage]({{ $page->link('tenant-storage') }}) are covered on separate pages. This page focuses on advanced usage, which can help you with writing nicer code.
+
+## `$data` {#data}
+
+An associative array that mirrors the tenant's data in the actual storage. It acts as a "cache" for [tenant storage methods]({{ $page->link('tenant-storage') }}). When you call `$tenant->get('foo')`, the `$data` property is checked for `'foo'` before trying to read from the storage. Similarly, when you call `$tenant->put()`, you write both to the actual storage and to the `$data` array.
+
+If you try to access the tenant's properties using `$tenant->foo` or `$tenant['foo']`, those calls are redirected to the `$data` array.
+
+The `put()` call always writes to the actual storage. If you do just:
+```php
+$tenant->foo = 'bar';
+```
+The data will not be persisted until you `->save()` the `$tenant`.
+
+## `$domains` {#domains}
+
+An array of domains that belong to the tenant.
+
+You may add and remove domains using the following methods:
+
+```php
+$tenant->addDomains(['foo.yourapp.com'])->save();
+$tenant->addDomains('foo.yourapp.com')->save();
+$tenant->removeDomains(['foo.yourapp.com'])->save();
+$tenant->removeDomains('foo.yourapp.com')->save();
+```
+
+> Don't forget to `->save()` after modifying the domains!
+
+## `$persisted` {#persisted}
+
+This property says whether the model has saved to the storage yet. In other words, if it's `false`, it's a new instance that has not been `->save()`d yet.
+
+## `->save()` {#save}
+
+If no ID is set in the tenant's `$data`, it will be generated using the `UniqueIDGenerator` specified in `config('tenancy.unique_id_generator')`.
+
+Then, if the object has been persisted, it's updated in storage. Otherwise, it's written to storage.
+
+## `->with()` {#with}
+
+You may fluently change the tenant's `$data` using `->with()`:
+```php
+$tenant->with('foo', 'bar'); // equivalent to $tenant->foo = $bar
+```
+
+Don't forget to `->save()` when you use `->with()`:
+```php
+$tenant->with('foo', 'bar')->with('abc', 'xyz')->save();
+```
+
+You may also use `->with<PropertyNameInPascalCase>` and it will be stored in snake case:
+```php
+>>> \Tenancy::find('b07aa3b0-dc68-11e9-9352-9159b2055c42')
+=> Stancl\Tenancy\Tenant {#3060
+     +data: [
+       "id" => "b07aa3b0-dc68-11e9-9352-9159b2055c42",
+     ],
+     +domains: [
+       "foo.localhost",
+     ],
+   }
+>>> \Tenancy::find('b07aa3b0-dc68-11e9-9352-9159b2055c42')
+    ->withPaypalApiKey('foobar')
+    ->save();
+
+=> Stancl\Tenancy\Tenant {#3087
+     +data: [
+       "id" => "b07aa3b0-dc68-11e9-9352-9159b2055c42",
+       "paypal_api_key" => "foobar",
+     ],
+     +domains: [
+       "foo.localhost",
+     ],
+   }
+```
+
+These methods make the most sense (= sound the best) during tenant creation:
+
+```php
+// $domains = ['foo.yourapp.com', 'foo.com'];
+$primary_domain = $domains[0];
+$id = $primary_domain . $this->randomString(24);
+
+Tenant::new()
+  ->withDomains($domains)
+  ->withPaypalApiKey('defaultApiKey');
+  ->withId($id)
+  ->save();
+```