From 9f344bf81d3112cf409f1603ed55e8aab72128fe Mon Sep 17 00:00:00 2001
From: Samuel Stancl <samuel@archte.ch>
Date: Thu, 25 Jun 2026 20:23:51 -0700
Subject: [PATCH] improve comments

---
 src/Bootstrappers/CacheTenancyBootstrapper.php  |  8 ++++----
 src/Bootstrappers/DatabaseCacheBootstrapper.php | 11 ++++++-----
 src/TenancyServiceProvider.php                  |  9 +++------
 3 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/src/Bootstrappers/CacheTenancyBootstrapper.php b/src/Bootstrappers/CacheTenancyBootstrapper.php
index d13ab9b5..74fc8490 100644
--- a/src/Bootstrappers/CacheTenancyBootstrapper.php
+++ b/src/Bootstrappers/CacheTenancyBootstrapper.php
@@ -18,11 +18,11 @@ use Stancl\Tenancy\Contracts\Tenant;
  * 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
  */
diff --git a/src/Bootstrappers/DatabaseCacheBootstrapper.php b/src/Bootstrappers/DatabaseCacheBootstrapper.php
index 391ab866..81611d0a 100644
--- a/src/Bootstrappers/DatabaseCacheBootstrapper.php
+++ b/src/Bootstrappers/DatabaseCacheBootstrapper.php
@@ -21,14 +21,15 @@ use Stancl\Tenancy\TenancyServiceProvider;
  *
  * 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
 {
diff --git a/src/TenancyServiceProvider.php b/src/TenancyServiceProvider.php
index c1c3e1fb..23d1ffab 100644
--- a/src/TenancyServiceProvider.php
+++ b/src/TenancyServiceProvider.php
@@ -99,8 +99,7 @@ class TenancyServiceProvider extends ServiceProvider
             // 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 */
@@ -108,10 +107,8 @@ class TenancyServiceProvider extends ServiceProvider
             });
 
             // 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);