Update ForgetTenantParameter-related comments

assets/config.php

@@ -92,12 +92,14 @@ return [
         /**
          * Identification middleware tenancy recognizes as path identification middleware.
          *
-         * This is used for determining if a path identification middleware is used
+         * This configuration is used to identify which middleware should trigger
-         * during operations specific to path identification, e.g. forgetting the tenant parameter in ForgetTenantParameter.
+         * conditionally removing the tenant parameter from routes using the ForgetTenantParameter listener.
+         *
+         * The listener only has an effect when path identification middleware is used in the global middleware stack
+         * and certain conditions are met (see ForgetTenantParameter for more info).
          *
          * If you're using a custom path identification middleware, add it here.
          *
-         * @see \Stancl\Tenancy\Actions\CloneRoutesAsTenant
          * @see \Stancl\Tenancy\Listeners\ForgetTenantParameter
          */
         'path_identification_middleware' => [

src/Listeners/ForgetTenantParameter.php

@@ -11,18 +11,18 @@ use Stancl\Tenancy\Resolvers\PathTenantResolver;
 // todo@earlyIdReview
 
 /**
- * Remove the tenant parameter from the matched route when path identification is used globally.
+ * Conditionally removes the tenant parameter from matched routes when using kernel path identification.
  *
- * While initializing tenancy, we forget the tenant parameter (in PathTenantResolver),
+ * When path identification middleware is in the global stack,
- * so that the route actions don't have to accept it.
+ * the tenant parameter is initially forgotten during tenancy initialization in PathTenantResolver.
+ * However, because kernel identification occurs before route matching, the route still contains
+ * the tenant parameter when RouteMatched is fired. This listener removes it to prevent route
+ * actions from needing to accept an unwanted tenant parameter.
  *
- * With kernel identification, tenancy gets initialized before the route gets matched.
+ * The {tenant} parameter is removed from the matched route only when ALL of these conditions are met:
- * The matched route gets the tenant parameter again, so we have to forget the parameter again on RouteMatched.
+ * 1) A path identification middleware is in the global middleware stack (kernel identification)
- *
+ * 2) The matched route does NOT have its own identification middleware (route-level identification takes precedence)
- * We remove the {tenant} parameter from the matched route when
+ * 3) The route is in tenant or universal context (central routes keep their tenant parameter)
- * 1) the InitializeTenancyByPath middleware is in the global stack, AND
- * 2) the matched route does not have identification middleware (so that {tenant} isn't forgotten when using route-level identification), AND
- * 3) the route isn't in the central context (so that {tenant} doesn't get accidentally removed from central routes).
  */
 class ForgetTenantParameter
 {

src/TenancyServiceProvider.php

@@ -152,6 +152,11 @@ class TenancyServiceProvider extends ServiceProvider
         Route::middlewareGroup('tenant', []);
         Route::middlewareGroup('central', []);
 
+        // Always register the ForgetTenantParameter listener
+        // even if path identification is not used.
+        //
+        // Though the listener really only has an effect
+        // when path identification is used in the global stack.
         Event::listen(RouteMatched::class, ForgetTenantParameter::class);
     }
 }