improve comments

Author: stancl

src/Bootstrappers/CacheTenancyBootstrapper.php

@@ -18,11 +18,11 @@
  * Makes cache tenant-aware by applying a prefix.
  *
  * Using this bootstrapper together with DatabaseTenancyBootstrapper
- * with a database cache store results in double scoping. The store is scoped by
- * DB connection (entries go into the tenant's database) *and* by the prefix. This is
- * harmless for most use cases, but can produce unexpected behavior.
+ * with a database cache store will result in "double scoping". The store will be scoped
+ * by the DB connection (entries will go into the tenant's database) *and* by the prefix.
+ * This is harmless in most cases, but is important to be aware of.
  *
- * If you're using a database cache store, use DatabaseCacheBootstrapper instead of this one.
+ * If you only use database cache stores, consider using DatabaseCacheBootstrapper instead.
  *
  * @see Stancl\Tenancy\Bootstrappers\DatabaseCacheBootstrapper
  */

src/Bootstrappers/DatabaseCacheBootstrapper.php

@@ -21,14 +21,15 @@
  *
  * By default, this bootstrapper scopes ALL cache stores that use the database driver. If you only
  * want to scope SOME stores, set the static $stores property to an array of names of the stores
- * you want to scope. These stores must use 'database' as their driver.
+ * you want to scope. Those stores must use 'database' as their driver.
  *
  * Notably, this bootstrapper sets TenancyServiceProvider::$adjustCacheManagerUsing to a callback
  * that ensures all affected stores still use the central connection when accessed via global cache
- * (typically the GlobalCache facade or global_cache() helper), even though this bootstrapper explicitly
- * sets the connection to tenant for all scoped cache stores. Extending database store on the global cache manager
- * cannot fix globalCache on its own because it reads 'tenant' from config (set by this bootstrapper), not null,
- * so the callback is still needed to correct the connection to central for globalCache.
+ * (typically the GlobalCache facade or global_cache() helper). The code in TenancyServiceProvider
+ * that uses `extend()` callbacks to make database stores on the global cache manager use the central
+ * connection only corrects stores scoped by the Database*Tenancy*Bootstrapper. This bootstrapper
+ * also changes the stores' connection in the *config* to 'tenant' which doesn't let that callback
+ * change the connection back to central on the global cache manager.
  */
 class DatabaseCacheBootstrapper implements TenancyBootstrapper
 {

src/TenancyServiceProvider.php

@@ -99,19 +99,16 @@ public function register(): void
             // config is null fall back to the default DB connection ('tenant'). Reset each
             // such store to its explicitly configured connection, or fall back to central.
             $centralConnection = $app['config']['tenancy.database.central_connection'];
-
-            $manager->extend('database', function ($app, array $config) use ($centralConnection) {
+            $manager->extend('database', function ($_app, array $config) use ($centralConnection) {
                 $config['connection'] ??= $centralConnection;
 
                 /** @var CacheManager $this */
                 return $this->createDatabaseDriver($config); // @phpstan-ignore method.protected
             });
 
             // DatabaseCacheBootstrapper explicitly writes 'tenant' into each store's 'connection'
-            // config. The database store extend above would then read 'tenant' as the
-            // configured value (not null) and use it directly, so the central connection fallback
-            // wouldn't be used.
-            //
+            // config. The extend() closure above would then read 'tenant' as the configured value
+            // (not null) and use it directly, so the central connection fallback wouldn't be used.
             // This callback is used to correct those connections back to central for globalCache.
             if (static::$adjustCacheManagerUsing !== null) {
                 (static::$adjustCacheManagerUsing)($manager);