Add tenancy()->central() helper (#526)

* Add tenancy()->central() helper

* Apply fixes from StyleCI

* Add docblock

* Fix return typehint

Co-authored-by: stancl <stancl@users.noreply.github.com>

src/Database/Concerns/TenantRun.php

@@ -8,6 +8,13 @@ use Stancl\Tenancy\Contracts\Tenant;
 
 trait TenantRun
 {
+    /**
+     * Run a callback in this tenant's context.
+     * Atomic, safely reverts to previous context.
+     *
+     * @param callable $callback
+     * @return mixed
+     */
     public function run(callable $callback)
     {
         /** @var Tenant $this */

src/Tenancy.php

@@ -103,6 +103,30 @@ class Tenancy
         return $this->model()->where($this->model()->getTenantKeyName(), $id)->first();
     }
 
+    /**
+     * Run a callback in the central context.
+     * Atomic, safely reverts to previous context.
+     *
+     * @param callable $callback
+     * @return mixed
+     */
+    public function central(callable $callback)
+    {
+        $previousTenant = $this->tenant;
+
+        $this->end();
+
+        // This callback will usually not accept arguments, but the previous
+        // Tenant is the only value that can be useful here, so we pass that.
+        $result = $callback($previousTenant);
+
+        if ($previousTenant) {
+            $this->initialize($previousTenant);
+        }
+
+        return $result;
+    }
+
     /**
      * Run a callback for multiple tenants.
      * More performant than running $tenant->run() one by one.