[4.x] Route cloning refactor (#1353)

* Refactor cloning action, update tests

* Delete redundant "should not be cloned" part from shouldBeCloned()

* Use 'clone' instead of a universal route in tenant parameter removal test

* Improve comment

* Add test for cloneRoutesWithMiddleware(), correct existing tests

* Allow cloning specific routes by name

* Fix typo in CloneActionTest

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* clean up CloneRoutesAsTenant, add a todo

* phpstan

* Add test for handling 'clone'  in MW groups

* Improve regression test

* Improve regression test

* Handle nested cloning flags in CloneRoutesAsTenant

* Ignore routes that are already considered tenant routes from cloning, update test accordingly

* Clarify cloning logic

* CloneRoutesAsTenant cleanup

* Rewrite clone action annotation, fix fluent usage bug

* Improve tests (comments, use $tenant->id instead of $tenant->getTenantKey())

* Test that the clone action can be used fluently without issues now (could serve as a regression test for the routesToClone change in previous commit)

* Minor annotation improvements

* Improve route cloning action docblock

* Add note about clearing the $routesToClone property

* improve docblock

* clean up tests

* fix typo

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Samuel Štancl <samuel@archte.ch>

src/Actions/CloneRoutesAsTenant.php

@@ -7,40 +7,72 @@ namespace Stancl\Tenancy\Actions;
 use Closure;
 use Illuminate\Routing\Route;
 use Illuminate\Routing\Router;
-use Illuminate\Support\Collection;
 use Illuminate\Support\Str;
-use Stancl\Tenancy\Enums\RouteMode;
 use Stancl\Tenancy\Resolvers\PathTenantResolver;
 
 /**
- * The CloneRoutesAsTenant action clones
+ * Clones either all existing routes for which shouldBeCloned() returns true
- * routes flagged with the 'universal' middleware,
+ * (by default, all routes with any middleware present in $cloneRoutesWithMiddleware),
- * all routes without a flag if the default route mode is universal,
+ * or if any routes were manually added to $routesToClone using $action->cloneRoute($route),
- * and routes that directly use the InitializeTenancyByPath middleware.
+ * clone just the routes in $routesToClone. This means that only the routes specified
+ * by cloneRoute() (which can be chained infinitely -- you can specify as many routes as you want)
+ * will be cloned.
  *
- * The main purpose of this action is to make the integration
+ * The main purpose of this action is to make the integration of packages
- * of packages (e.g., Jetstream or Livewire) easier with path-based tenant identification.
+ * (e.g., Jetstream or Livewire) easier with path-based tenant identification.
  *
- * By default, universal routes are cloned as tenant routes (= they get flagged with the 'tenant' middleware)
+ * The default for $cloneRoutesWithMiddleware is ['clone'].
- * and prefixed with the '/{tenant}' path prefix. Their name also gets prefixed with the tenant name prefix.
+ * If $routesToClone is empty, all routes with any middleware specified in $cloneRoutesWithMiddleware will be cloned.
+ * The middleware can be in a group, nested as deep as you want
+ * (e.g. if a route has a 'foo' middleware which is a group containing the 'clone' middleware, the route will be cloned).
  *
- * Routes with the path identification middleware get cloned similarly, but only if they're not universal at the same time.
+ * You may customize $cloneRoutesWithMiddleware using cloneRoutesWithMiddleware() to make any middleware of your choice trigger cloning.
- * Unlike universal routes, these routes don't get the tenant flag,
+ * By providing a callback to shouldClone(), you can change how it's determined if a route should be cloned if you don't want to use middleware flags.
- * because they don't need it (they're not universal, and they have the identification MW, so they're already considered tenant).
  *
- * You can use the `cloneUsing()` hook to customize the route definitions,
+ * Cloned routes are prefixed with '/{tenant}', flagged with 'tenant' middleware, and have their names prefixed with 'tenant.'.
- * and the `skipRoute()` method to skip cloning of specific routes.
+ * The parameter name and prefix can be changed e.g. to `/{team}` and `team.` by configuring the path resolver (tenantParameterName and tenantRouteNamePrefix).
- * You can also use the $tenantParameterName and $tenantRouteNamePrefix
+ * Routes with names that are already prefixed won't be cloned - but that's just the default behavior.
- * static properties to customize the tenant parameter name or the route name prefix.
+ * The cloneUsing() method allows you to completely override the default behavior and customize how the cloned routes will be defined.
  *
- * Note that routes already containing the tenant parameter or prefix won't be cloned.
+ * After cloning, only top-level middleware in $cloneRoutesWithMiddleware will be removed
+ * from the new route (so by default, 'clone' will be omitted from the new route's MW).
+ * Middleware groups are preserved as-is, even if they contain cloning middleware.
+ *
+ * Routes that already contain the tenant parameter or have names with the tenant prefix
+ * will not be cloned.
+ *
+ * Example usage:
+ * ```
+ * Route::get('/foo', fn () => true)->name('foo')->middleware('clone');
+ * Route::get('/bar', fn () => true)->name('bar')->middleware('universal');
+ *
+ * $cloneAction = app(CloneRoutesAsTenant::class);
+ *
+ * // Clone foo route as /{tenant}/foo/ and name it tenant.foo ('clone' middleware won't be present in the cloned route)
+ * $cloneAction->handle();
+ *
+ * // Clone bar route as /{tenant}/bar and name it tenant.bar ('universal' middleware won't be present in the cloned route)
+ * $cloneAction->cloneRoutesWithMiddleware(['universal'])->handle();
+ *
+ * Route::get('/baz', fn () => true)->name('baz');
+ *
+ * // Clone baz route as /{tenant}/bar and name it tenant.baz ('universal' middleware won't be present in the cloned route)
+ * $cloneAction->cloneRoute('baz')->handle();
+ * ```
+ *
+ * Calling handle() will also clear the $routesToClone array.
+ * This means that $action->cloneRoute('foo')->handle() will clone the 'foo' route, but subsequent calls to handle() will behave
+ * as if cloneRoute() wasn't called at all ($routesToClone will be empty).
+ * Note that calling handle() does not reset the other properties.
+ *
+ * @see Stancl\Tenancy\Resolvers\PathTenantResolver
  */
 class CloneRoutesAsTenant
 {
-    protected array $cloneRouteUsing = [];
+    protected array $routesToClone = [];
-    protected array $skippedRoutes = [
+    protected Closure|null $cloneUsing = null; // The callback should accept Route instance or the route name (string)
-        'stancl.tenancy.asset',
+    protected Closure|null $shouldClone = null;
-    ];
+    protected array $cloneRoutesWithMiddleware = ['clone'];
 
     public function __construct(
         protected Router $router,
@@ -48,100 +80,77 @@ class CloneRoutesAsTenant
 
     public function handle(): void
     {
-        $this->getRoutesToClone()->each(fn (Route $route) => $this->cloneRoute($route));
+        // 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())
+                ->filter(fn (Route $route) => $this->shouldBeCloned($route))
+                ->all();
+        }
+
+        foreach ($this->routesToClone as $route) {
+            // If the cloneUsing callback is set,
+            // use the callback to clone the route instead of the default
+            if ($this->cloneUsing) {
+                ($this->cloneUsing)($route);
+
+                continue;
+            }
+
+            if (is_string($route)) {
+                $this->router->getRoutes()->refreshNameLookups();
+                $route = $this->router->getRoutes()->getByName($route);
+            }
+
+            $this->copyMiscRouteProperties($route, $this->createNewRoute($route));
+        }
+
+        // Clean up the routesToClone array after cloning so that subsequent calls aren't affected
+        $this->routesToClone = [];
 
         $this->router->getRoutes()->refreshNameLookups();
     }
 
-    /**
+    public function cloneUsing(Closure|null $cloneUsing): static
-     * Make the action clone a specific route using the provided callback instead of the default one.
-     */
-    public function cloneUsing(string $routeName, Closure $callback): static
     {
-        $this->cloneRouteUsing[$routeName] = $callback;
+        $this->cloneUsing = $cloneUsing;
 
         return $this;
     }
 
-    /**
+    public function cloneRoutesWithMiddleware(array $middleware): static
-     * Skip a route's cloning.
-     */
-    public function skipRoute(string $routeName): static
     {
-        $this->skippedRoutes[] = $routeName;
+        $this->cloneRoutesWithMiddleware = $middleware;
 
         return $this;
     }
 
-    /**
+    public function shouldClone(Closure|null $shouldClone): static
-     * @return Collection<int, Route>
-     */
-    protected function getRoutesToClone(): Collection
     {
-        $tenantParameterName = PathTenantResolver::tenantParameterName();
+        $this->shouldClone = $shouldClone;
 
-        /**
+        return $this;
-         * Clone all routes that:
+    }
-         * - don't have the tenant parameter
+
-         * - aren't in the $skippedRoutes array
+    public function cloneRoute(Route|string $route): static
-         * - are using path identification (kernel or route-level).
+    {
-         *
+        $this->routesToClone[] = $route;
-         * Non-universal cloned routes will only be available in the tenant context,
+
-         * universal routes will be available in both contexts.
+        return $this;
-         */
+    }
-        return collect($this->router->getRoutes()->get())->filter(function (Route $route) use ($tenantParameterName) {
+
-            if (
+    protected function shouldBeCloned(Route $route): bool
-                tenancy()->routeHasMiddleware($route, 'tenant') ||
+    {
-                in_array($route->getName(), $this->skippedRoutes, true) ||
+        // Don't clone routes that already have tenant parameter or prefix
-                in_array($tenantParameterName, $route->parameterNames(), true)
+        if ($this->routeIsTenant($route)) {
-            ) {
             return false;
         }
 
-            $pathIdentificationMiddleware = config('tenancy.identification.path_identification_middleware');
+        if ($this->shouldClone) {
-            $routeHasPathIdentificationMiddleware = tenancy()->routeHasMiddleware($route, $pathIdentificationMiddleware);
+            return ($this->shouldClone)($route);
-            $routeHasNonPathIdentificationMiddleware = tenancy()->routeHasIdentificationMiddleware($route) && ! $routeHasPathIdentificationMiddleware;
-            $pathIdentificationMiddlewareInGlobalStack = tenancy()->globalStackHasMiddleware($pathIdentificationMiddleware);
-
-            /**
-             * The route should get cloned if:
-             * - it has route-level path identification middleware, OR
-             * - it uses kernel path identification (it doesn't have any route-level identification middleware) and the route is tenant or universal.
-             *
-             * The route is considered tenant if:
-             * - it's flagged as tenant, OR
-             * - it's not flagged as tenant or universal, but it has the identification middleware
-             *
-             * The route is considered universal if it's flagged as universal, and it doesn't have the tenant flag
-             * (it's still considered universal if it has route-level path identification middleware + the universal flag).
-             *
-             * If the route isn't flagged, the context is determined using the default route mode.
-             */
-            $pathIdentificationUsed = (! $routeHasNonPathIdentificationMiddleware) &&
-                ($routeHasPathIdentificationMiddleware || $pathIdentificationMiddlewareInGlobalStack);
-
-            return $pathIdentificationUsed &&
-                (tenancy()->getRouteMode($route) === RouteMode::UNIVERSAL || tenancy()->routeHasMiddleware($route, 'clone'));
-        });
         }
 
-    /**
+        return tenancy()->routeHasMiddleware($route, $this->cloneRoutesWithMiddleware);
-     * Clone a route using a callback specified in the $cloneRouteUsing property (using the cloneUsing method).
-     * If there's no callback specified for the route, use the default way of cloning routes.
-     */
-    protected function cloneRoute(Route $route): void
-    {
-        $routeName = $route->getName();
-
-        // If the route's cloning callback exists
-        // Use the callback to clone the route instead of the default way of cloning routes
-        if ($routeName && $customRouteCallback = data_get($this->cloneRouteUsing, $routeName)) {
-            $customRouteCallback($route);
-
-            return;
-        }
-
-        $this->copyMiscRouteProperties($route, $this->createNewRoute($route));
     }
 
     protected function createNewRoute(Route $route): Route
@@ -150,33 +159,24 @@ class CloneRoutesAsTenant
         $prefix = trim($route->getPrefix() ?? '', '/');
         $uri = $route->getPrefix() ? Str::after($route->uri(), $prefix) : $route->uri();
 
-        $newRouteAction = collect($route->action)->tap(function (Collection $action) use ($route, $prefix) {
+        $action = collect($route->action);
-            /** @var array $routeMiddleware */
-            $routeMiddleware = $action->get('middleware') ?? [];
 
         // Make the new route have the same middleware as the original route
         // Add the 'tenant' middleware to the new route
-            // Exclude `universal` and `clone` middleware from the new route (it should only be flagged as tenant)
+        // Exclude $this->cloneRoutesWithMiddleware MW from the new route (it should only be flagged as tenant)
-            $newRouteMiddleware = collect($routeMiddleware)
-                ->merge(['tenant']) // Add 'tenant' flag
-                ->filter(fn (string $middleware) => ! in_array($middleware, ['universal', 'clone']))
-                ->toArray();
 
-            $tenantRouteNamePrefix = PathTenantResolver::tenantRouteNamePrefix();
+        $middleware = $this->processMiddlewareForCloning($action->get('middleware') ?? []);
 
-            // Make sure the route name has the tenant route name prefix
+        if ($name = $route->getName()) {
-            $newRouteNamePrefix = $route->getName()
+            $action->put('as', PathTenantResolver::tenantRouteNamePrefix() . $name);
-                ? $tenantRouteNamePrefix . Str::after($route->getName(), $tenantRouteNamePrefix)
+        }
-                : null;
 
-            return $action
+        $action
-                ->put('as', $newRouteNamePrefix)
+            ->put('middleware', $middleware)
-                ->put('middleware', $newRouteMiddleware)
             ->put('prefix', $prefix . '/{' . PathTenantResolver::tenantParameterName() . '}');
-        })->toArray();
 
         /** @var Route $newRoute */
-        $newRoute = $this->router->$method($uri, $newRouteAction);
+        $newRoute = $this->router->$method($uri, $action->toArray());
 
         return $newRoute;
     }
@@ -194,4 +194,26 @@ class CloneRoutesAsTenant
             ->withTrashed($originalRoute->allowsTrashedBindings())
             ->setDefaults($originalRoute->defaults);
     }
+
+    /** Removes top-level cloneRoutesWithMiddleware and adds 'tenant' middleware. */
+    protected function processMiddlewareForCloning(array $middleware): array
+    {
+        $processedMiddleware = array_filter(
+            $middleware,
+            fn ($mw) => ! in_array($mw, $this->cloneRoutesWithMiddleware)
+        );
+
+        $processedMiddleware[] = 'tenant';
+
+        return array_unique($processedMiddleware);
+    }
+
+    /** Check if route already has tenant parameter or name prefix. */
+    protected function routeIsTenant(Route $route): bool
+    {
+        $routeHasTenantParameter = in_array(PathTenantResolver::tenantParameterName(), $route->parameterNames());
+        $routeHasTenantPrefix = $route->getName() && str_starts_with($route->getName(), PathTenantResolver::tenantRouteNamePrefix());
+
+        return $routeHasTenantParameter || $routeHasTenantPrefix;
+    }
 }

tests/CloneActionTest.php

@@ -1,270 +1,195 @@
 <?php
 
 use Illuminate\Routing\Route;
-use Stancl\Tenancy\Enums\RouteMode;
 use Stancl\Tenancy\Tests\Etc\Tenant;
-use Illuminate\Contracts\Http\Kernel;
 use Stancl\Tenancy\Actions\CloneRoutesAsTenant;
 use Stancl\Tenancy\Resolvers\PathTenantResolver;
 use Illuminate\Support\Facades\Route as RouteFacade;
-use Stancl\Tenancy\Tests\Etc\HasMiddlewareController;
-use Stancl\Tenancy\Middleware\InitializeTenancyByPath;
-use Stancl\Tenancy\Middleware\InitializeTenancyByDomain;
 use function Stancl\Tenancy\Tests\pest;
 
-test('a route can be universal using path identification', function (array $routeMiddleware, array $globalMiddleware) {
+test('CloneRoutesAsTenant action clones routes with clone middleware by default', function () {
-    foreach ($globalMiddleware as $middleware) {
+    config(['tenancy.identification.resolvers.' . PathTenantResolver::class . '.tenant_parameter_name' => 'team']);
-        if ($middleware === 'universal') {
+    config(['tenancy.identification.resolvers.' . PathTenantResolver::class . '.tenant_route_name_prefix' => 'team-route.']);
-            config(['tenancy.default_route_mode' => RouteMode::UNIVERSAL]);
-        } else {
-            app(Kernel::class)->pushMiddleware($middleware);
-        }
-    }
 
-    RouteFacade::get('/foo', function () {
+    // Should not be cloned
-        return tenancy()->initialized
+    RouteFacade::get('/central', fn () => true)->name('central');
-            ? 'Tenancy is initialized.'
-            : 'Tenancy is not initialized.';
-    })->middleware($routeMiddleware);
 
-    config(['tenancy._tests.static_identification_middleware' => $routeMiddleware]);
+    // Should be cloned since no specific routes are passed to the action using cloneRoute() and the route has the 'clone' middleware
+    RouteFacade::get('/foo', fn () => true)->middleware(['clone'])->name('foo');
 
-    RouteFacade::get('/bar', [HasMiddlewareController::class, 'index']);
+    $originalRoutes = RouteFacade::getRoutes()->get();
 
     /** @var CloneRoutesAsTenant $cloneRoutesAction */
     $cloneRoutesAction = app(CloneRoutesAsTenant::class);
 
     $cloneRoutesAction->handle();
 
-    $tenantKey = Tenant::create()->getTenantKey();
+    $newRoutes = collect(RouteFacade::getRoutes()->get())->filter(fn ($route) => ! in_array($route, $originalRoutes));
 
-    pest()->get("http://localhost/foo")
+    expect($newRoutes->count())->toEqual(1);
-        ->assertSuccessful()
-        ->assertSee('Tenancy is not initialized.');
 
-    pest()->get("http://localhost/{$tenantKey}/foo")
+    $newRoute = $newRoutes->first();
-        ->assertSuccessful()
+    expect($newRoute->uri())->toBe('{team}/foo');
-        ->assertSee('Tenancy is initialized.');
-
-    tenancy()->end();
-
-    pest()->get("http://localhost/bar")
-        ->assertSuccessful()
-        ->assertSee('Tenancy is not initialized.');
-
-    pest()->get("http://localhost/{$tenantKey}/bar")
-        ->assertSuccessful()
-        ->assertSee('Tenancy is initialized.');
-})->with('path identification types');
-
-test('CloneRoutesAsTenant registers prefixed duplicates of universal routes correctly', function (bool $kernelIdentification, bool $useController, string $tenantMiddleware) {
-    $routeMiddleware = ['universal'];
-    config(['tenancy.identification.path_identification_middleware' => [$tenantMiddleware]]);
-
-    if ($kernelIdentification) {
-        app(Kernel::class)->pushMiddleware($tenantMiddleware);
-    } else {
-        $routeMiddleware[] = $tenantMiddleware;
-    }
-
-    config(['tenancy.identification.resolvers.' . PathTenantResolver::class . '.tenant_parameter_name' => $tenantParameterName = 'team']);
-    config(['tenancy.identification.resolvers.' . PathTenantResolver::class . '.tenant_route_name_prefix' => $tenantRouteNamePrefix = 'team-route.']);
-
-    // Test that routes with controllers as well as routes with closure actions get cloned correctly
-    $universalRoute = RouteFacade::get('/home', $useController ? Controller::class : fn () => tenant() ? 'Tenancy is initialized.' : 'Tenancy is not initialized.')->middleware($routeMiddleware)->name('home');
-    $centralRoute = RouteFacade::get('/central', fn () => true)->name('central');
-
-    config(['tenancy._tests.static_identification_middleware' => $routeMiddleware]);
-
-    $universalRoute2 = RouteFacade::get('/bar', [HasMiddlewareController::class, 'index'])->name('second-home');
-
-    expect($routes = RouteFacade::getRoutes()->get())->toContain($universalRoute)
-        ->toContain($universalRoute2)
-        ->toContain($centralRoute);
-
-    /** @var CloneRoutesAsTenant $cloneRoutesAction */
-    $cloneRoutesAction = app(CloneRoutesAsTenant::class);
-
-    $cloneRoutesAction->handle();
-
-    expect($routesAfterRegisteringDuplicates = RouteFacade::getRoutes()->get())
-        ->toContain($universalRoute)
-        ->toContain($centralRoute);
-
-    $newRoutes = collect($routesAfterRegisteringDuplicates)->filter(fn ($route) => ! in_array($route, $routes));
-
-    expect($newRoutes->first()->uri())->toBe('{' . $tenantParameterName . '}' . '/' . $universalRoute->uri());
-    expect($newRoutes->last()->uri())->toBe('{' . $tenantParameterName . '}' . '/' . $universalRoute2->uri());
-
-    // Universal flag is excluded from the route middleware
-    expect(tenancy()->getRouteMiddleware($newRoutes->first()))
-        ->toEqualCanonicalizing(
-            array_values(array_filter(array_merge(tenancy()->getRouteMiddleware($universalRoute), ['tenant']),
-            fn($middleware) => $middleware !== 'universal'))
-        );
-
-    // Universal flag is provided statically in the route's controller, so we cannot exclude it
-    expect(tenancy()->getRouteMiddleware($newRoutes->last()))
-        ->toEqualCanonicalizing(
-            array_values(array_merge(tenancy()->getRouteMiddleware($universalRoute2), ['tenant']))
-        );
 
     $tenant = Tenant::create();
 
-    pest()->get(route($centralRouteName = $universalRoute->getName()))->assertSee('Tenancy is not initialized.');
+    expect($newRoute->getName())->toBe('team-route.foo');
-    pest()->get(route($centralRouteName2 = $universalRoute2->getName()))->assertSee('Tenancy is not initialized.');
+    pest()->get(route('team-route.foo', ['team' => $tenant->id]))->assertOk();
-    pest()->get(route($tenantRouteName = $newRoutes->first()->getName(), [$tenantParameterName => $tenant->getTenantKey()]))->assertSee('Tenancy is initialized.');
+    expect(tenancy()->getRouteMiddleware($newRoute))
-    tenancy()->end();
+        ->toContain('tenant')
-    pest()->get(route($tenantRouteName2 = $newRoutes->last()->getName(), [$tenantParameterName => $tenant->getTenantKey()]))->assertSee('Tenancy is initialized.');
+        ->not()->toContain('clone');
+});
 
-    expect($tenantRouteName)->toBe($tenantRouteNamePrefix . $universalRoute->getName());
+test('CloneRoutesAsTenant action clones only specified routes when using cloneRoute()', function () {
-    expect($tenantRouteName2)->toBe($tenantRouteNamePrefix . $universalRoute2->getName());
+    config(['tenancy.identification.resolvers.' . PathTenantResolver::class . '.tenant_parameter_name' => 'team']);
-    expect($centralRouteName)->toBe($universalRoute->getName());
+    config(['tenancy.identification.resolvers.' . PathTenantResolver::class . '.tenant_route_name_prefix' => 'team-route.']);
-    expect($centralRouteName2)->toBe($universalRoute2->getName());
-})->with([
-    'kernel identification' => true,
-    'route-level identification' => false,
-// Creates a matrix (multiple with())
-])->with([
-    'use controller' => true,
-    'use closure' => false
-])->with([
-    'path identification middleware' => InitializeTenancyByPath::class,
-    'custom path identification middleware' => CustomInitializeTenancyByPath::class,
-]);
 
-test('CloneRoutesAsTenant only clones routes with path identification by default', function () {
+    // Should not be cloned
-    app(Kernel::class)->pushMiddleware(InitializeTenancyByPath::class);
+    RouteFacade::get('/central', fn () => true)->name('central');
 
-    $currentRouteCount = fn () => count(RouteFacade::getRoutes()->get());
+    // Should not be cloned despite having clone middleware because cloneRoute() is used
+    RouteFacade::get('/foo', fn () => true)->middleware(['clone'])->name('foo');
 
-    $initialRouteCount = $currentRouteCount();
+    // The only route that should be cloned
+    $routeToClone = RouteFacade::get('/home', fn () => true)->name('home');
 
-    // Path identification is used globally, and this route doesn't use a specific identification middleware, meaning path identification is used and the route should get cloned
+    $originalRoutes = RouteFacade::getRoutes()->get();
-    RouteFacade::get('/home', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')->middleware('universal')->name('home');
-    // The route uses a specific identification middleware other than InitializeTenancyByPath – the route shouldn't get cloned
-    RouteFacade::get('/home-domain-id', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')->middleware(['universal', InitializeTenancyByDomain::class])->name('home-domain-id');
-
-    expect($currentRouteCount())->toBe($newRouteCount = $initialRouteCount + 2);
 
     /** @var CloneRoutesAsTenant $cloneRoutesAction */
     $cloneRoutesAction = app(CloneRoutesAsTenant::class);
 
+    // If a specific route is passed to the action, clone only that route (cloneRoute() can be chained as many times as needed)
+    $cloneRoutesAction->cloneRoute($routeToClone);
+
     $cloneRoutesAction->handle();
 
-    // Only one of the two routes gets cloned
+    $newRoutes = collect(RouteFacade::getRoutes()->get())->filter(fn ($route) => ! in_array($route, $originalRoutes));
-    expect($currentRouteCount())->toBe($newRouteCount + 1);
+
+    expect($newRoutes->count())->toEqual(1);
+
+    $newRoute = $newRoutes->first();
+    expect($newRoute->uri())->toBe('{team}/home');
+
+    $tenant = Tenant::create();
+
+    expect($newRoute->getName())->toBe('team-route.home');
+    pest()->get(route('team-route.home', ['team' => $tenant->id]))->assertOk();
+    expect(tenancy()->getRouteMiddleware($newRoute))
+        ->toContain('tenant')
+        ->not()->toContain('clone');
+
+    // Verify that the route with clone middleware was NOT cloned
+    expect(RouteFacade::getRoutes()->getByName('team-route.foo'))->toBeNull();
 });
 
-test('custom callbacks can be used for cloning universal routes', function () {
+test('all routes with any of the middleware specified in cloneRoutesWithMiddleware will be cloned by default', function (array $cloneRoutesWithMiddleware) {
-    RouteFacade::get('/home', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')->middleware(['universal', InitializeTenancyByPath::class])->name($routeName = 'home');
+    RouteFacade::get('/foo', fn () => true)->name('foo');
+    RouteFacade::get('/bar', fn () => true)->name('bar')->middleware(['clone']);
+    RouteFacade::get('/baz', fn () => true)->name('baz')->middleware(['duplicate']);
+
+    $currentRouteCount = fn () => count(RouteFacade::getRoutes()->get());
+    $initialRouteCount = $currentRouteCount();
+
+    /** @var CloneRoutesAsTenant $cloneRoutesAction */
+    $cloneRoutesAction = app(CloneRoutesAsTenant::class);
+
+    $cloneRoutesAction
+        ->cloneRoutesWithMiddleware($cloneRoutesWithMiddleware)
+        ->handle();
+
+    // Each middleware is only used on a single route so we assert that the count of new routes matches the count of used middleware flags
+    expect($currentRouteCount())->toEqual($initialRouteCount + count($cloneRoutesWithMiddleware));
+})->with([
+    [[]],
+    [['duplicate']],
+    [['clone', 'duplicate']],
+]);
+
+test('custom callback can be used for specifying if a route should be cloned', function () {
+    RouteFacade::get('/home', fn () => true)->name('home');
 
     /** @var CloneRoutesAsTenant $cloneRoutesAction */
     $cloneRoutesAction = app(CloneRoutesAsTenant::class);
     $currentRouteCount = fn () => count(RouteFacade::getRoutes()->get());
     $initialRouteCount = $currentRouteCount();
 
-    $cloneRoutesAction;
+    // No routes should be cloned
+    $cloneRoutesAction
+        ->shouldClone(fn (Route $route) => false)
+        ->handle();
 
-    // Skip cloning the 'home' route
+    // Expect route count to stay the same because cloning essentially gets turned off
-    $cloneRoutesAction->cloneUsing($routeName, function (Route $route) {
-        return;
-    })->handle();
-
-    // Expect route count to stay the same because the 'home' route cloning gets skipped
     expect($initialRouteCount)->toEqual($currentRouteCount());
 
-    // Modify the 'home' route cloning so that a different route is cloned
+    // Only the 'home' route should be cloned
-    $cloneRoutesAction->cloneUsing($routeName, function (Route $route) {
+    $cloneRoutesAction
-        RouteFacade::get('/cloned-route', fn () => true)->name('new.home');
+        ->shouldClone(fn (Route $route) => $route->getName() === 'home')
-    })->handle();
+        ->handle();
 
     expect($currentRouteCount())->toEqual($initialRouteCount + 1);
 });
 
-test('cloning of specific routes can get skipped', function () {
+test('custom callbacks can be used for customizing the creation of the cloned routes', function () {
-    RouteFacade::get('/home', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')->middleware('universal')->name($routeName = 'home');
+    RouteFacade::get('/foo', fn () => true)->name('foo')->middleware(['clone']);
+    RouteFacade::get('/bar', fn () => true)->name('bar')->middleware(['clone']);
 
     /** @var CloneRoutesAsTenant $cloneRoutesAction */
     $cloneRoutesAction = app(CloneRoutesAsTenant::class);
+
+    $cloneRoutesAction
+        ->cloneUsing(function (Route $route) {
+            RouteFacade::get('/cloned/' . $route->uri(), fn () => 'cloned route')->name('cloned.' . $route->getName());
+        })->handle();
+
+    expect(route('cloned.foo', absolute: false))->toBe('/cloned/foo');
+    expect(route('cloned.bar', absolute: false))->toBe('/cloned/bar');
+
+    pest()->get(route('cloned.foo'))->assertSee('cloned route');
+    pest()->get(route('cloned.bar'))->assertSee('cloned route');
+});
+
+test('the clone action can clone specific routes either using name or route instance', function (bool $cloneRouteByName) {
+    RouteFacade::get('/foo', fn () => true)->name('foo');
+    $barRoute = RouteFacade::get('/bar', fn () => true)->name('bar');
+    RouteFacade::get('/baz', fn () => true)->name('baz');
+
     $currentRouteCount = fn () => count(RouteFacade::getRoutes()->get());
     $initialRouteCount = $currentRouteCount();
 
-    // Skip cloning the 'home' route
+    /** @var CloneRoutesAsTenant $cloneRoutesAction */
-    $cloneRoutesAction->skipRoute($routeName);
+    $cloneRoutesAction = app(CloneRoutesAsTenant::class);
 
-    $cloneRoutesAction->handle();
+    // A route instance or a route name can be passed to cloneRoute()
+    $cloneRoutesAction->cloneRoute($cloneRouteByName ? $barRoute->getName() : $barRoute)->handle();
 
-    // Expect route count to stay the same because the 'home' route cloning gets skipped
+    // Exactly one route should be cloned
-    expect($initialRouteCount)->toEqual($currentRouteCount());
+    expect($currentRouteCount())->toEqual($initialRouteCount + 1);
-});
 
-test('routes except nonuniversal routes with path id mw are given the tenant flag after cloning', function (array $routeMiddleware, array $globalMiddleware) {
+    expect(RouteFacade::getRoutes()->getByName('tenant.bar'))->not()->toBeNull();
-    foreach ($globalMiddleware as $middleware) {
+})->with([
-        if ($middleware === 'universal') {
+    true,
-            config(['tenancy.default_route_mode' => RouteMode::UNIVERSAL]);
+    false,
-        } else {
+]);
-            app(Kernel::class)->pushMiddleware($middleware);
-        }
-    }
-
-    $route = RouteFacade::get('/home', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')
-        ->middleware($routeMiddleware)
-        ->name($routeName = 'home');
-
-    app(CloneRoutesAsTenant::class)->handle();
-
-    $clonedRoute = RouteFacade::getRoutes()->getByName('tenant.' . $routeName);
-
-    // Non-universal routes with identification middleware are already considered tenant, so they don't get the tenant flag
-    if (! tenancy()->routeIsUniversal($route) && tenancy()->routeHasIdentificationMiddleware($clonedRoute)) {
-        expect($clonedRoute->middleware())->not()->toContain('tenant');
-    } else {
-        expect($clonedRoute->middleware())->toContain('tenant');
-    }
-})->with('path identification types');
-
-test('routes with the clone flag get cloned without making the routes universal', function ($identificationMiddleware) {
-    config(['tenancy.identification.path_identification_middleware' => [$identificationMiddleware]]);
-
-    RouteFacade::get('/home', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')
-        ->middleware(['clone', $identificationMiddleware])
-        ->name($routeName = 'home');
-
-    $tenant = Tenant::create();
-
-    app(CloneRoutesAsTenant::class)->handle();
-
-    $clonedRoute = RouteFacade::getRoutes()->getByName('tenant.' . $routeName);
-
-    expect(array_values($clonedRoute->middleware()))->toEqualCanonicalizing(['tenant', $identificationMiddleware]);
-
-    // The original route is not accessible
-    pest()->get(route($routeName))->assertServerError();
-    pest()->get(route($routeName, ['tenant' => $tenant]))->assertServerError();
-    // The cloned route is a tenant route
-    pest()->get(route('tenant.' . $routeName, ['tenant' => $tenant]))->assertSee('Tenancy initialized.');
-})->with([InitializeTenancyByPath::class, CustomInitializeTenancyByPath::class]);
 
 test('the clone action prefixes already prefixed routes correctly', function () {
     $routes = [
-        RouteFacade::get('/home', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')
+        RouteFacade::get('/home', fn () => true)
-            ->middleware(['universal', InitializeTenancyByPath::class])
+            ->middleware(['clone'])
             ->name('home')
             ->prefix('prefix'),
 
-        RouteFacade::get('/leadingAndTrailingSlash', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')
+        RouteFacade::get('/leadingAndTrailingSlash', fn () => true)
-            ->middleware(['universal', InitializeTenancyByPath::class])
+            ->middleware(['clone'])
             ->name('leadingAndTrailingSlash')
             ->prefix('/prefix/'),
 
-        RouteFacade::get('/leadingSlash', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')
+        RouteFacade::get('/leadingSlash', fn () => true)
-            ->middleware(['universal', InitializeTenancyByPath::class])
+            ->middleware(['clone'])
             ->name('leadingSlash')
             ->prefix('/prefix'),
 
-        RouteFacade::get('/trailingSlash', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')
+        RouteFacade::get('/trailingSlash', fn () => true)
-            ->middleware(['universal', InitializeTenancyByPath::class])
+            ->middleware(['clone'])
             ->name('trailingSlash')
             ->prefix('prefix/'),
     ];
@@ -286,14 +211,14 @@ test('the clone action prefixes already prefixed routes correctly', function ()
 
         expect($clonedRouteUrl)
             // Original prefix does not occur in the cloned route's URL
-            ->not()->toContain("prefix/{$tenant->getTenantKey()}/prefix")
+            ->not()->toContain("prefix/{$tenant->id}/prefix")
             ->not()->toContain("//prefix")
             ->not()->toContain("prefix//")
-            // Route is prefixed correctly
+            // Instead, the route is prefixed correctly
-            ->toBe("http://localhost/prefix/{$tenant->getTenantKey()}/{$routes[$key]->getName()}");
+            ->toBe("http://localhost/prefix/{$tenant->id}/{$routes[$key]->getName()}");
 
         // The cloned route is accessible
-        pest()->get($clonedRouteUrl)->assertSee('Tenancy initialized.');
+        pest()->get($clonedRouteUrl)->assertOk();
     }
 });
 
@@ -301,12 +226,12 @@ test('clone action trims trailing slashes from prefixes given to nested route gr
     RouteFacade::prefix('prefix')->group(function () {
         RouteFacade::prefix('')->group(function () {
             // This issue seems to only happen when there's a group with a prefix, then a group with an empty prefix, and then a / route
-            RouteFacade::get('/', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')
+            RouteFacade::get('/', fn () => true)
-                ->middleware(['universal', InitializeTenancyByPath::class])
+                ->middleware(['clone'])
                 ->name('landing');
 
-            RouteFacade::get('/home', fn () => tenant() ? 'Tenancy initialized.' : 'Tenancy not initialized.')
+            RouteFacade::get('/home', fn () => true)
-                ->middleware(['universal', InitializeTenancyByPath::class])
+                ->middleware(['clone'])
                 ->name('home');
         });
     });
@@ -316,35 +241,99 @@ test('clone action trims trailing slashes from prefixes given to nested route gr
     $clonedLandingUrl = route('tenant.landing', ['tenant' => $tenant = Tenant::create()]);
     $clonedHomeRouteUrl = route('tenant.home', ['tenant' => $tenant]);
 
+    $landingRoute = RouteFacade::getRoutes()->getByName('tenant.landing');
+    $homeRoute = RouteFacade::getRoutes()->getByName('tenant.home');
+
+    expect($landingRoute->uri())->toBe('prefix/{tenant}');
+    expect($homeRoute->uri())->toBe('prefix/{tenant}/home');
+
     expect($clonedLandingUrl)
         ->not()->toContain("prefix//")
-        ->toBe("http://localhost/prefix/{$tenant->getTenantKey()}");
+        ->toBe("http://localhost/prefix/{$tenant->id}");
 
     expect($clonedHomeRouteUrl)
         ->not()->toContain("prefix//")
-        ->toBe("http://localhost/prefix/{$tenant->getTenantKey()}/home");
+        ->toBe("http://localhost/prefix/{$tenant->id}/home");
 });
 
-class CustomInitializeTenancyByPath extends InitializeTenancyByPath
+test('tenant routes are ignored from cloning and clone middleware in groups causes no issues', function () {
-{
+    // Should NOT be cloned, already has tenant parameter
+    RouteFacade::get("/{tenant}/route-with-tenant-parameter", fn () => true)
+        ->middleware(['clone'])
+        ->name("tenant.route-with-tenant-parameter");
 
-}
+    // Should NOT be cloned, already has tenant name prefix
+    RouteFacade::get("/route-with-tenant-name-prefix", fn () => true)
+        ->middleware(['clone'])
+        ->name("tenant.route-with-tenant-name-prefix");
 
-dataset('path identification types', [
+    // Should NOT be cloned, already has tenant parameter + 'clone' middleware in group
-    'kernel identification' => [
+    // 'clone' MW in groups won't be removed (this doesn't cause any issues)
-        ['universal'], // Route middleware
+    RouteFacade::middlewareGroup('group', ['auth', 'clone']);
-        [InitializeTenancyByPath::class], // Global Global middleware
+    RouteFacade::get("/{tenant}/route-with-clone-in-mw-group", fn () => true)
-    ],
+        ->middleware('group')
-    'route-level identification' => [
+        ->name("tenant.route-with-clone-in-mw-group");
-        ['universal', InitializeTenancyByPath::class], // Route middleware
+
-        [], // Global middleware
+    // SHOULD be cloned (has clone middleware)
-    ],
+    RouteFacade::get('/foo', fn () => true)
-    'kernel identification + defaulting to universal routes' => [
+        ->middleware(['clone'])
-        [], // Route middleware
+        ->name('foo');
-        ['universal', InitializeTenancyByPath::class], // Global middleware
+
-    ],
+    // SHOULD be cloned (has nested clone middleware)
-    'route-level identification + defaulting to universal routes' => [
+    RouteFacade::get('/bar', fn () => true)
-        [InitializeTenancyByPath::class],  // Route middleware
+        ->middleware(['group'])
-        ['universal'], // Global middleware
+        ->name('bar');
-    ],
+
-]);
+    $cloneAction = app(CloneRoutesAsTenant::class);
+    $initialRouteCount = count(RouteFacade::getRoutes()->get());
+
+    // Run clone action multiple times
+    $cloneAction->handle();
+    $firstRunCount = count(RouteFacade::getRoutes()->get());
+
+    $cloneAction->handle();
+    $secondRunCount = count(RouteFacade::getRoutes()->get());
+
+    $cloneAction->handle();
+    $thirdRunCount = count(RouteFacade::getRoutes()->get());
+
+    // Two route should have been cloned, and only once
+    expect($firstRunCount)->toBe($initialRouteCount + 2);
+    // No new routes on subsequent runs
+    expect($secondRunCount)->toBe($firstRunCount);
+    expect($thirdRunCount)->toBe($firstRunCount);
+
+    // Verify the correct routes were cloned
+    expect(RouteFacade::getRoutes()->getByName('tenant.foo'))->toBeInstanceOf(Route::class);
+    expect(RouteFacade::getRoutes()->getByName('tenant.bar'))->toBeInstanceOf(Route::class);
+
+    // Tenant routes were not duplicated
+    $allRouteNames = collect(RouteFacade::getRoutes()->get())->map->getName()->filter();
+    expect($allRouteNames->filter(fn($name) => str_contains($name, 'route-with-tenant-parameter'))->count())->toBe(1);
+    expect($allRouteNames->filter(fn($name) => str_contains($name, 'route-with-tenant-name-prefix'))->count())->toBe(1);
+    expect($allRouteNames->filter(fn($name) => str_contains($name, 'route-with-clone-in-mw-group'))->count())->toBe(1);
+});
+
+test('clone action can be used fluently', function() {
+    RouteFacade::get('/foo', fn () => true)->name('foo')->middleware('clone');
+    RouteFacade::get('/bar', fn () => true)->name('bar')->middleware('universal');
+
+    $cloneAction = app(CloneRoutesAsTenant::class);
+
+    // Clone foo route
+    $cloneAction->handle();
+    expect(collect(RouteFacade::getRoutes()->get())->map->getName())
+        ->toContain('tenant.foo');
+
+    // Clone bar route
+    $cloneAction->cloneRoutesWithMiddleware(['universal'])->handle();
+    expect(collect(RouteFacade::getRoutes()->get())->map->getName())
+        ->toContain('tenant.foo', 'tenant.bar');
+
+    RouteFacade::get('/baz', fn () => true)->name('baz');
+
+    // Clone baz route
+    $cloneAction->cloneRoute('baz')->handle();
+    expect(collect(RouteFacade::getRoutes()->get())->map->getName())
+        ->toContain('tenant.foo', 'tenant.bar', 'tenant.baz');
+});

tests/EarlyIdentificationTest.php

@@ -344,9 +344,9 @@ test('the tenant parameter is only removed from tenant routes when using path id
             ->middleware('tenant')
             ->name('tenant-route');
 
-        RouteFacade::get($pathIdentification ? '/universal-route' : '/universal-route/{tenant?}', [ControllerWithMiddleware::class, 'routeHasTenantParameter'])
+        RouteFacade::get($pathIdentification ? '/cloned-route' : '/cloned-route/{tenant?}', [ControllerWithMiddleware::class, 'routeHasTenantParameter'])
-            ->middleware('universal')
+            ->middleware('clone')
-            ->name('universal-route');
+            ->name('cloned-route');
 
         /** @var CloneRoutesAsTenant */
         $cloneRoutesAction = app(CloneRoutesAsTenant::class);
@@ -364,8 +364,8 @@ test('the tenant parameter is only removed from tenant routes when using path id
             $response = pest()->get($tenantKey . '/tenant-route')->assertOk();
             expect((bool) $response->getContent())->toBeFalse();
 
-            // The tenant parameter gets removed from the cloned universal route
+            // The tenant parameter gets removed from the cloned route
-            $response = pest()->get($tenantKey . '/universal-route')->assertOk();
+            $response = pest()->get($tenantKey . '/cloned-route')->assertOk();
             expect((bool) $response->getContent())->toBeFalse();
         } else {
             // Tenant parameter is not removed from tenant routes using other kernel identification MW
@@ -374,12 +374,12 @@ test('the tenant parameter is only removed from tenant routes when using path id
             $response = pest()->get("http://{$domain}/{$tenantKey}/tenant-route")->assertOk();
             expect((bool) $response->getContent())->toBeTrue();
 
-            // The tenant parameter does not get removed from the universal route when accessing it through the central domain
+            // The tenant parameter does not get removed from the cloned route when accessing it through the central domain
-            $response = pest()->get("http://localhost/universal-route/$tenantKey")->assertOk();
+            $response = pest()->get("http://localhost/cloned-route/$tenantKey")->assertOk();
             expect((bool) $response->getContent())->toBeTrue();
 
-            // The tenant parameter gets removed from the universal route when accessing it through the tenant domain
+            // The tenant parameter gets removed from the cloned route when accessing it through the tenant domain
-            $response = pest()->get("http://{$domain}/universal-route")->assertOk();
+            $response = pest()->get("http://{$domain}/cloned-route")->assertOk();
             expect((bool) $response->getContent())->toBeFalse();
         }
     } else {