From 032bf08040ed7b8419d5dc84b87e159ba2a8594b Mon Sep 17 00:00:00 2001
From: lukinovec <lukinovec@gmail.com>
Date: Fri, 9 Sep 2022 19:03:53 +0200
Subject: [PATCH] Document making a command tenant-aware (#196)

* Copy and modify v2 tenant aware commands docs page

* Add navigation link to the tenant-aware commands page

* Use the v2 tenant-aware commands page and slightly modify it
---
 navigation.php                                |  1 +
 source/docs/v3/tenant-aware-commands.blade.md | 61 +++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 source/docs/v3/tenant-aware-commands.blade.md

diff --git a/navigation.php b/navigation.php
index 65c3caf..75dded2 100644
--- a/navigation.php
+++ b/navigation.php
@@ -209,6 +209,7 @@ return [
                     ],
                 ],
                 'Console commands' => 'console-commands',
+                'Tenant-aware commands' => 'tenant-aware-commands',
                 'Tenant attribute encryption' => 'tenant-attribute-encryption',
                 'Cached lookup' => 'cached-lookup',
                 'Real-time facades' => 'realtime-facades',
diff --git a/source/docs/v3/tenant-aware-commands.blade.md b/source/docs/v3/tenant-aware-commands.blade.md
new file mode 100644
index 0000000..6e1b3f7
--- /dev/null
+++ b/source/docs/v3/tenant-aware-commands.blade.md
@@ -0,0 +1,61 @@
+---
+title: Tenant-aware commands
+description: Tenant-aware commands
+extends: _layouts.documentation
+section: content
+---
+
+# Tenant-aware commands {#tenant-aware-commands}
+
+Even though [`tenants:run`]({{ $page->link('console-commands#run') }}) lets you run arbitrary artisan commands for tenants, you may want to have strictly tenant commands.
+
+To make a command tenant-aware, utilize the `TenantAwareCommand` trait:
+```php
+class MyCommand extends Command
+{
+    use TenantAwareCommand;
+}
+```
+
+However, this trait requires you to implement a `getTenants()` method that returns an array of `Tenant` instances.
+
+If you don't want to implement the options/arguments yourself, you may use one of these two traits:
+- `HasATenantsOption` - accepts multiple tenant IDs, optional -- by default the command is executed for all tenants
+- `HasATenantArgument` - accepts a single tenant ID, required argument
+
+These traits implement the `getTenants()` method needed by `TenantAwareCommand`.
+
+> Note: If you're using a custom constructor for your command, you need to add `$this->specifyParameters()` at the end for the option/argument traits to take effect.
+
+So if you use these traits in combination with `TenantAwareCommand`, you won't have to change a thing in your command:
+
+```php
+class FooCommand extends Command
+{
+    use TenantAwareCommand, HasATenantsOption;
+
+    public function handle()
+    {
+        //
+    }
+}
+
+class BarCommand extends Command
+{
+    use TenantAwareCommand, HasATenantArgument;
+
+    public function handle()
+    {
+        //
+    }
+}
+```
+
+### Custom implementation
+
+If you want more control, you may implement this functionality yourself by simply accepting a `tenant_id` argument and then inside `handle()` doing something like this:
+```php
+tenancy()->find($this->argument('tenant_id'))->run(function () {
+    // Your actual command code
+});
+```