[4.x] Add tenant parameter to defaults() in UrlGeneratorBootstrapper (#1311)

* Pass tenant parameter using defaults in UrlGeneratorBootstrapper, update tests accordingly (wip)

* Fix code style (php-cs-fixer)

* Update bootstrapper

* Improve TenancyUrlGenerator docblocks

* Improve bootstrapper/TenancyUrlGenerator tests (WIP)

* Improve route() name prefixing test

* Keep  `UrlGeneratorBootstrapper::$addTenantParameterToDefaults` disabled by default

* Add `$override` functionality  to TenancyUrlGenerator

* Test $override functionality, update new defaults in the bootstrapper tests

* Fix code style (php-cs-fixer)

* Update comments

* Update routeNameOverride()

* cleanup

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Samuel Štancl <samuel@archte.ch>

src/Bootstrappers/UrlGeneratorBootstrapper.php

@@ -10,6 +10,7 @@ use Illuminate\Support\Facades\URL;
 use Stancl\Tenancy\Contracts\TenancyBootstrapper;
 use Stancl\Tenancy\Contracts\Tenant;
 use Stancl\Tenancy\Overrides\TenancyUrlGenerator;
+use Stancl\Tenancy\Resolvers\PathTenantResolver;
 
 /**
  * Makes the app use TenancyUrlGenerator (instead of Illuminate\Routing\UrlGenerator) which:
@@ -19,10 +20,20 @@ use Stancl\Tenancy\Overrides\TenancyUrlGenerator;
  * Used with path and query string identification.
  *
  * @see TenancyUrlGenerator
- * @see \Stancl\Tenancy\Resolvers\PathTenantResolver
+ * @see PathTenantResolver
  */
 class UrlGeneratorBootstrapper implements TenancyBootstrapper
 {
+    /**
+     * Should the tenant route parameter get added to TenancyUrlGenerator::defaults().
+     *
+     * This is recommended when using path identification since defaults() generally has better support in integrations,
+     * namely Ziggy, compared to TenancyUrlGenerator::$passTenantParameterToRoutes.
+     *
+     * With query string identification, this has no effect since URL::defaults() only works for route paramaters.
+     */
+    public static bool $addTenantParameterToDefaults = true;
+
     public function __construct(
         protected Application $app,
         protected UrlGenerator $originalUrlGenerator,
@@ -32,7 +43,7 @@ class UrlGeneratorBootstrapper implements TenancyBootstrapper
     {
         URL::clearResolvedInstances();
 
-        $this->useTenancyUrlGenerator();
+        $this->useTenancyUrlGenerator($tenant);
     }
 
     public function revert(): void
@@ -45,7 +56,7 @@ class UrlGeneratorBootstrapper implements TenancyBootstrapper
      *
      * @see \Illuminate\Routing\RoutingServiceProvider registerUrlGenerator()
      */
-    protected function useTenancyUrlGenerator(): void
+    protected function useTenancyUrlGenerator(Tenant $tenant): void
     {
         $newGenerator = new TenancyUrlGenerator(
             $this->app['router']->getRoutes(),
@@ -53,7 +64,16 @@ class UrlGeneratorBootstrapper implements TenancyBootstrapper
             $this->app['config']->get('app.asset_url'),
         );
 
-        $newGenerator->defaults($this->originalUrlGenerator->getDefaultParameters());
+        $defaultParameters = $this->originalUrlGenerator->getDefaultParameters();
+
+        if (static::$addTenantParameterToDefaults) {
+            $defaultParameters = array_merge(
+                $defaultParameters,
+                [PathTenantResolver::tenantParameterName() => $tenant->getTenantKey()]
+            );
+        }
+
+        $newGenerator->defaults($defaultParameters);
 
         $newGenerator->setSessionResolver(function () {
             return $this->app['session'] ?? null;

src/Overrides/TenancyUrlGenerator.php

@@ -13,39 +13,77 @@ use Stancl\Tenancy\Resolvers\PathTenantResolver;
 /**
  * This class is used in place of the default UrlGenerator when UrlGeneratorBootstrapper is enabled.
  *
- * TenancyUrlGenerator does two extra things:
- * 1. Autofill the {tenant} parameter in the tenant context with the current tenant if $passTenantParameterToRoutes is enabled (enabled by default)
- * 2. Prepend the route name with `tenant.` (or the configured prefix) if $prefixRouteNames is enabled (disabled by default)
+ * TenancyUrlGenerator does a few extra things:
+ *   - Autofills the tenant parameter in the tenant context with the current tenant.
+ *     This is done either by:
+ *       - URL::defaults() -- if UrlGeneratorBootstrapper::$addTenantParameterToDefaults is enabled.
+ *         This generally has the best support since tools like e.g. Ziggy read defaults().
+ *       - Automatically passing ['tenant' => ...] to each route() call -- if TenancyUrlGenerator::$passTenantParameterToRoutes is enabled
+ *         This is a more universal solution since it supports both path identification and query parameter identification.
  *
- * Both of these can be skipped by passing the $bypassParameter (`['central' => true]` by default)
+ *   - Prepends route names passed to route() and URL::temporarySignedRoute()
+ *     with `tenant.` (or the configured prefix) if $prefixRouteNames is enabled.
+ *     This is primarily useful when using route cloning with path identification.
+ *
+ * To bypass this behavior on any single route() call, pass the $bypassParameter as true (['central' => true] by default).
  */
 class TenancyUrlGenerator extends UrlGenerator
 {
     /**
-     * Parameter which bypasses the behavior modification of route() and temporarySignedRoute().
+     * Parameter which works as a flag for bypassing the behavior modification of route() and temporarySignedRoute().
      *
-     * E.g. route('tenant') => app.test/{tenant}/tenant (or app.test/tenant?tenant=tenantKey if the route doesn't accept the tenant parameter)
-     * route('tenant', [$bypassParameter => true]) => app.test/tenant.
+     * For example, in tenant context:
+     * Route::get('/', ...)->name('home');
+     * // query string identification
+     * Route::get('/tenant', ...)->middleware(InitializeTenancyByRequestData::class)->name('tenant.home');
+     * - route('home') => app.test/tenant?tenant=tenantKey
+     * - route('home', [$bypassParameter => true]) => app.test/
+     * - route('tenant.home', [$bypassParameter => true]) => app.test/tenant -- no query string added
+     *
+     * Note: UrlGeneratorBootstrapper::$addTenantParameterToDefaults is not affected by this, though
+     * it doesn't matter since it doesn't pass any extra parameters when not needed.
+     *
+     * @see UrlGeneratorBootstrapper
      */
     public static string $bypassParameter = 'central';
 
     /**
-     * Determine if the route names passed to `route()` or `temporarySignedRoute()`
-     * should get prefixed with the tenant route name prefix.
+     * Should route names passed to route() or temporarySignedRoute()
+     * get prefixed with the tenant route name prefix.
      *
-     * This is useful when using path identification with packages that generate URLs,
-     * like Jetstream, so that you don't have to manually prefix route names passed to each route() call.
+     * This is useful when using e.g. path identification with third-party packages
+     * where you don't have control over all route() calls or don't want to change
+     * too many files. Often this will be when using route cloning.
      */
     public static bool $prefixRouteNames = false;
 
     /**
-     * Determine if the tenant parameter should get passed
-     * to the links generated by `route()` or `temporarySignedRoute()` whenever available
-     * (enabled by default – works with both path and query string identification).
+     * Should the tenant parameter be passed to route() or temporarySignedRoute() calls.
      *
-     * With path identification, you can disable this and use URL::defaults() instead (as an alternative solution).
+     * This is useful with path or query parameter identification. The former can be handled
+     * more elegantly using UrlGeneratorBootstrapper::$addTenantParameterToDefaults.
+     *
+     * @see UrlGeneratorBootstrapper
      */
-    public static bool $passTenantParameterToRoutes = true;
+    public static bool $passTenantParameterToRoutes = false;
+
+    /**
+     * Route name overrides.
+     *
+     * Note: This behavior can be bypassed using $bypassParameter just like
+     * $prefixRouteNames and $passTenantParameterToRoutes.
+     *
+     * Example from a Jetstream integration:
+     * [
+     *     'profile.show' => 'tenant.profile.show',
+     *     'two-factor.login' => 'tenant.two-factor.login',
+     * ]
+     *
+     * In the tenant context:
+     * - `route('profile.show')` will return a URL as if you called `route('tenant.profile.show')`.
+     * - `route('profile.show', ['central' => true])` will return a URL as if you called `route('profile.show')`.
+     */
+    public static array $overrides = [];
 
     /**
      * Override the route() method so that the route name gets prefixed
@@ -99,7 +137,7 @@ class TenancyUrlGenerator extends UrlGenerator
     protected function prepareRouteInputs(string $name, array $parameters): array
     {
         if (! $this->routeBehaviorModificationBypassed($parameters)) {
-            $name = $this->prefixRouteName($name);
+            $name = $this->routeNameOverride($name) ?? $this->prefixRouteName($name);
             $parameters = $this->addTenantParameter($parameters);
         }
 
@@ -124,10 +162,15 @@ class TenancyUrlGenerator extends UrlGenerator
     }
 
     /**
-     * If `tenant()` isn't null, add tenant paramter to the passed parameters.
+     * If `tenant()` isn't null, add the tenant parameter to the passed parameters.
      */
     protected function addTenantParameter(array $parameters): array
     {
         return tenant() && static::$passTenantParameterToRoutes ? array_merge($parameters, [PathTenantResolver::tenantParameterName() => tenant()->getTenantKey()]) : $parameters;
     }
+
+    protected function routeNameOverride(string $name): string|null
+    {
+        return static::$overrides[$name] ?? null;
+    }
 }