From 9029bcd46542e9e062a8a6d05d0c28e7c6c21608 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samuel=20=C5=A0tancl?= <samuel.stancl@gmail.com>
Date: Sat, 17 Aug 2019 10:53:00 +0200
Subject: [PATCH] wip

---
 ...32874a7a12af04c860216712abd81de88798a3.php |  85 -------------
 ...4e3aadb9b8963f7000eb1c55904e566c57e81d.php |  15 ---
 navigation.php                                |   7 ++
 source/_layouts/master.blade.php              |   2 +-
 source/docs/console-commands.md               |  15 ++-
 ...ference-between-this-package-and-others.md |  22 ++++
 source/docs/getting-started.md                |   4 +-
 source/docs/https-certificates.md             |  40 +++++++
 source/docs/tenancy-initialization.md         |   8 +-
 source/docs/tenant-manager.md                 | 112 ++++++++++++++++++
 10 files changed, 202 insertions(+), 108 deletions(-)
 delete mode 100644 cache/7032874a7a12af04c860216712abd81de88798a3.php
 delete mode 100644 cache/7a4e3aadb9b8963f7000eb1c55904e566c57e81d.php
 create mode 100644 source/docs/difference-between-this-package-and-others.md
 create mode 100644 source/docs/https-certificates.md
 create mode 100644 source/docs/tenant-manager.md
diff --git a/cache/7032874a7a12af04c860216712abd81de88798a3.php b/cache/7032874a7a12af04c860216712abd81de88798a3.php
deleted file mode 100644
index 1a95d288..00000000
--- a/cache/7032874a7a12af04c860216712abd81de88798a3.php
+++ /dev/null
@@ -1,85 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-    <head>
-        <meta charset="utf-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
-        <meta http-equiv="x-ua-compatible" content="ie=edge">
-        <meta name="description" content="<?php echo e($page->description ?? $page->siteDescription); ?>">
-
-        <meta property="og:site_name" content="<?php echo e($page->siteName); ?>"/>
-        <meta property="og:title" content="<?php echo e($page->title ? $page->title.' | ' : ''); ?><?php echo e($page->siteName); ?>"/>
-        <meta property="og:description" content="<?php echo e($page->description ?? $page->siteDescription); ?>"/>
-        <meta property="og:url" content="<?php echo e($page->getUrl()); ?>"/>
-        <meta property="og:image" content="/assets/img/logo.png"/>
-        <meta property="og:type" content="website"/>
-
-        <meta name="twitter:image:alt" content="<?php echo e($page->siteName); ?>">
-        <meta name="twitter:card" content="summary_large_image">
-
-        <?php if ($page->docsearchApiKey && $page->docsearchIndexName): ?>
-            <meta name="generator" content="tighten_jigsaw_doc">
-        <?php endif; ?>
-
-        <title><?php echo e($page->siteName); ?><?php echo e($page->title ? ' | '.$page->title : ''); ?></title>
-
-        <link rel="home" href="<?php echo e($page->baseUrl); ?>">
-        <link rel="icon" href="/favicon.ico">
-
-        <?php echo $__env->yieldPushContent('meta'); ?>
-
-        <?php if ($page->production): ?>
-            <!-- Insert analytics code here -->
-        <?php endif; ?>
-
-        <link href="https://fonts.googleapis.com/css?family=Nunito+Sans:300,300i,400,400i,700,700i,800,800i" rel="stylesheet">
-        <link rel="stylesheet" href="<?php echo e(mix('css/main.css', 'assets/build')); ?>">
-
-        <?php if ($page->docsearchApiKey && $page->docsearchIndexName): ?>
-            <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />
-        <?php endif; ?>
-    </head>
-
-    <body class="flex flex-col justify-between min-h-screen bg-grey-lightest text-grey-darkest leading-normal font-sans">
-        <header class="flex items-center shadow bg-white border-b h-24 mb-8 py-4" role="banner">
-            <div class="container flex items-center max-w-4xl mx-auto px-4 lg:px-8">
-                <div class="flex items-center">
-                    <a href="/" title="<?php echo e($page->siteName); ?> home" class="inline-flex items-center">
-                        
-
-                        <h1 class="text-lg md:text-2xl text-blue-darkest font-semibold hover:text-blue-dark my-0 pr-4"><?php echo e($page->siteName); ?></h1>
-                    </a>
-                </div>
-
-                <div class="flex flex-1 justify-end items-center text-right md:pl-10">
-                    <?php if ($page->docsearchApiKey && $page->docsearchIndexName): ?>
-                        <?php echo $__env->make('_nav.search-input', \Illuminate\Support\Arr::except(get_defined_vars(), ['__data', '__path']))->render(); ?>
-                    <?php endif; ?>
-                </div>
-            </div>
-
-            <?php echo $__env->yieldContent('nav-toggle'); ?>
-        </header>
-
-        <main role="main" class="w-full flex-auto">
-            <?php echo $__env->yieldContent('body'); ?>
-        </main>
-
-        <script src="<?php echo e(mix('js/main.js', 'assets/build')); ?>"></script>
-
-        <?php echo $__env->yieldPushContent('scripts'); ?>
-
-        <footer class="bg-white text-center text-sm mt-12 py-4" role="contentinfo">
-            <ul class="flex flex-col md:flex-row justify-center list-reset">
-                <li class="md:mr-2">
-                    &copy; <a href="https://github.com/stancl" title="Samuel Štancl">Samuel Štancl</a> <?php echo e(date('Y')); ?>.
-                </li>
-
-                <li>
-                    Built with <a href="http://jigsaw.tighten.co" title="Jigsaw by Tighten">Jigsaw</a>
-                    and <a href="https://tailwindcss.com" title="Tailwind CSS, a utility-first CSS framework">Tailwind CSS</a>.
-                </li>
-            </ul>
-        </footer>
-    </body>
-</html>
-<?php /**PATH /home/samuel/Projects/tenancy-docs/source/_layouts/master.blade.php ENDPATH**/ ?>
\ No newline at end of file
diff --git a/cache/7a4e3aadb9b8963f7000eb1c55904e566c57e81d.php b/cache/7a4e3aadb9b8963f7000eb1c55904e566c57e81d.php
deleted file mode 100644
index fbf02795..00000000
--- a/cache/7a4e3aadb9b8963f7000eb1c55904e566c57e81d.php
+++ /dev/null
@@ -1,15 +0,0 @@
-<?php $__env->startSection('body'); ?>
-<div class="flex flex-col items-center mt-32 text-grey-darker">
-    <h1 class="text-6xl font-light leading-none mb-2">404</h1>
-
-    <h2 class="text-3xl">Page not found</h2>
-
-    <hr class="block w-full max-w-sm mx-auto my-8 border">
-
-    <p class="text-xl">
-        Need to update this page? See the <a title="404 Page Documentation" href="https://jigsaw.tighten.co/docs/custom-404-page/"> Jigsaw documentation</a>.
-    </p>
-</div>
-<?php $__env->stopSection(); ?>
-
-<?php echo $__env->make('_layouts.master', \Illuminate\Support\Arr::except(get_defined_vars(), ['__data', '__path']))->render(); ?><?php /**PATH /home/samuel/Projects/tenancy-docs/source/404.blade.php ENDPATH**/ ?>
\ No newline at end of file
diff --git a/navigation.php b/navigation.php
index 2cb7fa17..444f74e4 100644
--- a/navigation.php
+++ b/navigation.php
@@ -6,6 +6,7 @@ return [
         'children' => [
             'Installation'    => 'docs/installation',
             'Storage Drivers' => 'docs/storage-drivers',
+            'This Package vs Others'   => 'docs/difference-between-this-package-and-others',
             'Configuration'   => 'docs/configuration',
         ],
     ],
@@ -15,6 +16,7 @@ return [
             'Creating Tenants' => 'docs/creating-tenants',
             'Tenant Routes'    => 'docs/tenant-routes',
             'Tenant Storage'   => 'docs/tenant-storage',
+            'Tenant Manager'   => 'docs/tenant-manager',
             'Console Commands' => 'docs/console-commands',
         ],
     ],
@@ -27,6 +29,11 @@ return [
             'Development'              => 'docs/development',
         ],
     ],
+    'Tips' => [
+        'children' => [
+            'HTTPS Certificates' => 'docs/https-certificates',
+        ],
+    ],
     'Stay Updated' => 'docs/stay-updated',
     'GitHub'       => 'https://github.com/stancl/tenancy',
 ];
diff --git a/source/_layouts/master.blade.php b/source/_layouts/master.blade.php
index 0bfcc0c1..2641076a 100644
--- a/source/_layouts/master.blade.php
+++ b/source/_layouts/master.blade.php
@@ -20,7 +20,7 @@
             <meta name="generator" content="tighten_jigsaw_doc">
         @endif
 
-        <title>{{ $page->siteName }}{{ $page->title ? ' | ' . $page->title : '' }}</title>
+        <title>{{ $page->title ? $page->title . ' | ' : '' }}{{ $page->siteName }}</title>
 
         <link rel="home" href="{{ $page->baseUrl }}">
         <link rel="icon" href="/favicon.ico">
diff --git a/source/docs/console-commands.md b/source/docs/console-commands.md
index e978b969..08422a51 100644
--- a/source/docs/console-commands.md
+++ b/source/docs/console-commands.md
@@ -7,7 +7,7 @@ section: content
 
 # Console Commands {#console-commands}
 
-The package comes with a couple of artisan commands.
+The package comes with some artisan commands that will help you during development.
 
 ## Migrate {#migrate}
 
@@ -38,7 +38,7 @@ Similarly to [migrate](#migrate), these commands accept a `--tenants` option.
 
 You can use the tenants:run command to run your own commands for tenants.
 
-If your command's signature were email:send {user} {--queue} {--subject} {body}, you would run this command like this:
+If your command's signature were `email:send {--queue} {--subject=} {body}`, you would run this command like this:
 ```
 php artisan tenants:run email:send --tenants=8075a580-1cb8-11e9-8822-49c5d8f8ff23 --option="queue=1" --option="subject=New Feature" --argument="body=We have launched a new feature. ..."
 ```
@@ -50,4 +50,13 @@ php artisan tenants:list
 Listing all tenants.
 [Tenant] uuid: dbe0b330-1a6e-11e9-b4c3-354da4b4f339 @ localhost
 [Tenant] uuid: 49670df0-1a87-11e9-b7ba-cf5353777957 @ dev.localhost
-```
\ No newline at end of file
+```
+
+## Selectively clearing tenant cache {#selectively-clearing-tenant-cache}
+
+You can delete specific tenants' cache by using the `--tags` option on `cache:clear`:
+```
+php artisan cache:clear --tags=tenantdbe0b330-1a6e-11e9-b4c3-354da4b4f339
+```
+
+The tag is `config('tenancy.cache.tag_base') . $uuid`.
\ No newline at end of file
diff --git a/source/docs/difference-between-this-package-and-others.md b/source/docs/difference-between-this-package-and-others.md
new file mode 100644
index 00000000..29843e3e
--- /dev/null
+++ b/source/docs/difference-between-this-package-and-others.md
@@ -0,0 +1,22 @@
+---
+title: Difference Between This Package And Others
+description: Difference Between This Package And Others | with stancl/tenancy — A Laravel multi-database tenancy package that respects your code.
+extends: _layouts.documentation
+section: content
+---
+
+# Difference Between This Package And Others
+
+A frequently asked question is the difference between this package and [tenancy/multi-tenant](https://github.com/tenancy/multi-tenant).
+
+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.
+
+## Which one should you use?
+
+Depends on what you prefer.
+
+If you want full control and make your application multi-tenant yourself, use tenancy/multi-tenant.
+
+If you want to focus on writing your application instead of tenancy implementations, use stancl/tenancy.
diff --git a/source/docs/getting-started.md b/source/docs/getting-started.md
index a45e3555..6d279009 100644
--- a/source/docs/getting-started.md
+++ b/source/docs/getting-started.md
@@ -7,11 +7,11 @@ section: content
 
 # Getting Started {#getting-started}
 
-todo tenancy end, todo deleting specific cache tags
+todo filesystem page
 
 [**stancl/tenancy**](https://github.com/stancl/tenancy) is a Laravel multi-database tenancy package. It is designed in a way that requires you to make no changes to your 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.
 
-> Note: Filesystem is the only thing that can be a little problematic. Be sure to read [that page](TODOfilesystem).
+> Note: Filesystem is the only thing that can be a little problematic. Be sure to read [that page](filesystem).
 
 ## How does it work? {#how-does-it-work}
 
diff --git a/source/docs/https-certificates.md b/source/docs/https-certificates.md
new file mode 100644
index 00000000..d693e32b
--- /dev/null
+++ b/source/docs/https-certificates.md
@@ -0,0 +1,40 @@
+---
+title: HTTPS Certificates
+description: HTTPS Certificates with stancl/tenancy — A Laravel multi-database tenancy package that respects your code..
+extends: _layouts.documentation
+section: content
+---
+
+# HTTPS certificates
+
+HTTPS certificates are very easy to deal with if you use the `yourclient1.yourapp.com`, `yourclient2.yourapp.com` model. You can use a wildcard HTTPS certificate.
+
+If you use the model where second level domains are used, there are multiple ways you can solve this.
+
+This guide focuses on nginx.
+
+### 1. Use nginx with the lua module
+
+Specifically, you're interested in the [`ssl_certificate_by_lua_block`](https://github.com/openresty/lua-nginx-module#ssl_certificate_by_lua_block) directive. Nginx doesn't support using variables such as the hostname in the `ssl_certificate` directive, which is why the lua module is needed.
+
+This approach lets you use one server block for all tenants.
+
+### 2. Add a simple server block for each tenant
+
+You can store most of your config in a file, such as `/etc/nginx/includes/tenant`, and include this file into tenant server blocks.
+
+```nginx
+server {
+  include includes/tenant;
+  server_name foo.bar;
+  # ssl_certificate /etc/foo/...;
+}
+```
+
+### Generating certificates
+
+You can generate a certificate using certbot. If you use the `--nginx` flag, you will need to run certbot as root. If you use the `--webroot` flag, you only need the user that runs it to have write access to the webroot directory (or perhaps webroot/.well-known is enough) and some certbot files (you can specify these using --work-dir, --config-dir and --logs-dir).
+
+Creating this config dynamically from PHP is not easy, but is probably feasible. Giving `www-data` write access to `/etc/nginx/sites-available/tenants.conf` should work.
+
+However, you still need to reload nginx configuration to apply the changes to configuration. This is problematic and I'm not sure if there is a simple and secure way to do this from PHP.
\ No newline at end of file
diff --git a/source/docs/tenancy-initialization.md b/source/docs/tenancy-initialization.md
index 9a847467..4001ffd8 100644
--- a/source/docs/tenancy-initialization.md
+++ b/source/docs/tenancy-initialization.md
@@ -7,7 +7,11 @@ section: content
 
 # Tenancy Initialization {#tenancy-initialization}
 
-When you, or the `InitializeTenancy` middleware, run `tenancy()->init()`, the `bootstrap()` method is called.
+Tenancy can be initialized by calling `tenancy()->init()`. The `InitializeTenancy` middleware calls this method automatically.
+
+You can end a tenancy session using `tenancy()->end()`. This is useful if you need to run multiple tenant sessions or a mixed tenant/non-tenant session in a single request/command.
+
+The `tenancy()->init()` method calls `bootstrap()`.
 
 This method switches database connection, Redis connection (if Redis tenancy is enabled), cache and filesystem root paths.
 
@@ -49,7 +53,7 @@ public function connect(string $database)
 
 public function createTenantConnection(string $database_name)
 {
-    // Create the `tenancy` database connection.
+    // Create the `tenant` database connection.
     $based_on = config('tenancy.database.based_on') ?: config('database.default');
     config()->set([
         'database.connections.tenant' => config('database.connections.' . $based_on),
diff --git a/source/docs/tenant-manager.md b/source/docs/tenant-manager.md
new file mode 100644
index 00000000..f9ed1e89
--- /dev/null
+++ b/source/docs/tenant-manager.md
@@ -0,0 +1,112 @@
+---
+title: Tenant Manager
+description: Tenant Manager | stancl/tenancy — A Laravel multi-database tenancy package that respects your code.
+extends: _layouts.documentation
+section: content
+---
+
+# Tenant Manager {#tenant-manager}
+
+This page documents a couple of other `TenantManager` methods you may find useful.
+
+### Finding tenant using UUID
+
+`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');
+=> [
+     "uuid" => "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"
+```
+
+### Finding tenant by domain
+
+You may use the second argument to specify the key(s) as a string/array.
+
+```php
+>>> tenant()->findByDomain('localhost');
+=> [
+     "uuid" => "b3ce3f90-1a88-11e9-a6b0-038c6337ae50",
+     "domain" => "localhost",
+   ]
+```
+
+### Accessing the array
+
+You can access the public array tenant of TenantManager like this:
+
+```php
+tenancy()->tenant
+```
+
+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.
+
+```php
+tenant('uuid'); // Does the same thing as tenant()->tenant['uuid']
+```
+
+### Getting all tenants
+
+This method returns a collection of arrays.
+
+```php
+>>> tenant()->all();
+=> Illuminate\Support\Collection {#2980
+     all: [
+       [
+         "uuid" => "32e20780-1a88-11e9-a051-4b6489a7edac",
+         "domain" => "localhost",
+       ],
+       [
+         "uuid" => "49670df0-1a87-11e9-b7ba-cf5353777957",
+         "domain" => "dev.localhost",
+       ],
+     ],
+   }
+>>> tenant()->all()->pluck('domain');
+=> Illuminate\Support\Collection {#2983
+     all: [
+       "localhost",
+       "dev.localhost",
+     ],
+   }
+```
+
+### 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']);
+=> 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'))
+=> "tenant67412a60-1c01-11e9-a9e9-f799baa56fd9"
+```
\ No newline at end of file
