From f1ba036eb9d97704435ab40f1b1c95ea77645e87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samuel=20=C5=A0tancl?= <samuel@archte.ch>
Date: Sun, 9 Nov 2025 01:27:29 +0100
Subject: [PATCH] Cloning: improve type annotations, add cloneRoutes() for
 convenience

---
 src/Actions/CloneRoutesAsTenant.php | 55 +++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 6 deletions(-)

diff --git a/src/Actions/CloneRoutesAsTenant.php b/src/Actions/CloneRoutesAsTenant.php
index abe2cbcd..6e988907 100644
--- a/src/Actions/CloneRoutesAsTenant.php
+++ b/src/Actions/CloneRoutesAsTenant.php
@@ -86,13 +86,27 @@ use Stancl\Tenancy\Resolvers\PathTenantResolver;
  */
 class CloneRoutesAsTenant
 {
+    /** @var list<Route|string> */
     protected array $routesToClone = [];
+
     protected bool $addTenantParameter = true;
     protected bool $tenantParameterBeforePrefix = true;
     protected string|null $domain = null;
-    protected Closure|null $cloneUsing = null; // The callback should accept Route instance or the route name (string)
+
+    /**
+     * The callback should accept a Route instance or the route name (string).
+     *
+     * @var ?Closure(Route|string): void
+     */
+    protected Closure|null $cloneUsing = null;
+
+    /** @var ?Closure(Route): bool */
     protected Closure|null $shouldClone = null;
+
+    /** @var list<string> */
     protected array $cloneRoutesWithMiddleware = ['clone'];
+
+    /** @var list<string> */
     protected array $addTenantMiddleware = ['tenant'];
 
     public function __construct(
@@ -110,9 +124,12 @@ class CloneRoutesAsTenant
         // If no routes were specified using cloneRoute(), get all routes
         // and for each, determine if it should be cloned
         if (! $this->routesToClone) {
-            $this->routesToClone = collect($this->router->getRoutes()->get())
+            /** @var list<Route> */
+            $routesToClone = collect($this->router->getRoutes()->get())
                 ->filter(fn (Route $route) => $this->shouldBeCloned($route))
                 ->all();
+
+            $this->routesToClone = $routesToClone;
         }
 
         foreach ($this->routesToClone as $route) {
@@ -126,7 +143,9 @@ class CloneRoutesAsTenant
 
             if (is_string($route)) {
                 $this->router->getRoutes()->refreshNameLookups();
-                $route = $this->router->getRoutes()->getByName($route);
+                $routeName = $route;
+                $route = $this->router->getRoutes()->getByName($routeName);
+                assert(! is_null($route), "Route [{$routeName}] was meant to be cloned but does not exist.");
             }
 
             $this->createNewRoute($route);
@@ -155,6 +174,8 @@ class CloneRoutesAsTenant
      * The tenant middleware to be added to the cloned route.
      *
      * If used with early identification, make sure to include 'tenant' in this array.
+     *
+     * @param list<string> $middleware
      */
     public function addTenantMiddleware(array $middleware): static
     {
@@ -171,7 +192,11 @@ class CloneRoutesAsTenant
         return $this;
     }
 
-    /** Provide a custom callback for cloning routes, instead of the default behavior. */
+    /**
+     * Provide a custom callback for cloning routes, instead of the default behavior.
+     *
+     * @param ?Closure(Route|string): void $cloneUsing
+     */
     public function cloneUsing(Closure|null $cloneUsing): static
     {
         $this->cloneUsing = $cloneUsing;
@@ -179,7 +204,11 @@ class CloneRoutesAsTenant
         return $this;
     }
 
-    /** Specify which middleware should serve as "flags" telling this action to clone those routes. */
+    /**
+     * Specify which middleware should serve as "flags" telling this action to clone those routes.
+     *
+     * @param list<string> $middleware
+     */
     public function cloneRoutesWithMiddleware(array $middleware): static
     {
         $this->cloneRoutesWithMiddleware = $middleware;
@@ -190,7 +219,9 @@ class CloneRoutesAsTenant
     /**
      * Provide a custom callback for determining whether a route should be cloned.
      * Overrides the default middleware-based detection.
-     * */
+     *
+     * @param Closure(Route): bool $shouldClone
+     */
     public function shouldClone(Closure|null $shouldClone): static
     {
         $this->shouldClone = $shouldClone;
@@ -213,6 +244,18 @@ class CloneRoutesAsTenant
         return $this;
     }
 
+    /**
+     * Clone individual routes.
+     *
+     * @param list<Route|string> $routes
+     */
+    public function cloneRoutes(array $routes): static
+    {
+        $this->routesToClone = array_merge($this->routesToClone, $routes);
+
+        return $this;
+    }
+
     protected function shouldBeCloned(Route $route): bool
     {
         // Don't clone routes that already have tenant parameter or prefix