Fix initializeCache() not clearing in-memory perms collection on tenant/cache switch

Fixes #2964

**Problem:**

`initializeCache()` re-resolves the cache store and config but leaves `$this->permissions` untouched. Since `PermissionRegistrar` is a singleton and `loadPermissions()` short-circuits when that collection is already populated:

```php
if ($this->permissions) {
    return;
}
```

any process that switches cache context mid-lifetime (multi-tenant apps switching tenants, queue workers, artisan commands looping over tenants, Octane workers) keeps serving the *previous* tenant's permissions after calling `initializeCache()` — **exactly the call our own docs recommend for this scenario**. Because `hasDirectPermission()` matches by primary key, and each tenant DB has independent auto-increment IDs, a leftover collection doesn't just serve stale data — it can resolve permission names to the wrong tenant's IDs and return incorrect authorization results.

**Fix:**
`initializeCache()` now also clears the in-memory permissions collection (via `clearPermissionsCollection()`) and the transient `$cachedRoles` buffer, so the next permission check rebuilds from the newly-configured cache/tenant instead of reusing stale data.

**Changes:**
- [`src/PermissionRegistrar.php`](src/PermissionRegistrar.php) — `initializeCache()` clears in-memory permissions/roles state.
- [`tests/Integration/PermissionRegistrarTest.php`](tests/Integration/PermissionRegistrarTest.php) — regression test asserting the loaded collection is `null` after `initializeCache()`.
- [`docs/advanced-usage/cache.md`](docs/advanced-usage/cache.md) — clarifies that `initializeCache()` now also discards the loaded collection.

**Impact:** No behavior change for typical single-tenant apps. `initializeCache()` is otherwise only called once at registrar construction, where `$permissions` is already `null`, so this adds no overhead there. It only changes behavior for the explicit-reinitialize-mid-request pattern our docs already describe, making that pattern actually work as documented.

Author: drbyte

docs/advanced-usage/cache.md

@@ -80,6 +80,8 @@ Tip: Most parts of your multitenancy app will relate to a single tenant during a
 app()->make(\Spatie\Permission\PermissionRegistrar::class)->initializeCache();
 ```
 
+`initializeCache()` also discards the registrar's in-memory permissions/roles collection (equivalent to `clearPermissionsCollection()`), so the next permission check reloads from the newly-configured cache/tenant instead of reusing the previous tenant's already-loaded collection.
+
 
 ### Custom Cache Store
 

src/PermissionRegistrar.php

@@ -76,6 +76,11 @@ public function initializeCache(): void
         $this->pivotPermission = config('permission.column_names.permission_pivot_key') ?: 'permission_id';
 
         $this->cache = $this->getCacheStoreFromConfig();
+
+        // Discard any in-memory permissions/roles loaded under the previous cache config,
+        // so a subsequent call rebuilds them from the new cache/tenant.
+        $this->clearPermissionsCollection();
+        $this->cachedRoles = [];
     }
 
     protected function getCacheStoreFromConfig(): Repository

tests/Integration/PermissionRegistrarTest.php

@@ -1,5 +1,6 @@
 <?php
 
+use Illuminate\Support\Facades\DB;
 use Spatie\Permission\Contracts\Permission as PermissionContract;
 use Spatie\Permission\Contracts\Role as RoleContract;
 use Spatie\Permission\Models\Permission as SpatiePermission;
@@ -22,6 +23,62 @@
     expect($reflectedProperty->getValue(app(PermissionRegistrar::class)))->toBeNull();
 });
 
+it('clears the loaded permissions collection when reinitializing the cache', function () {
+    $reflectedClass = new ReflectionClass(app(PermissionRegistrar::class));
+    $reflectedProperty = $reflectedClass->getProperty('permissions');
+    $reflectedProperty->setAccessible(true);
+
+    app(PermissionRegistrar::class)->getPermissions();
+
+    expect($reflectedProperty->getValue(app(PermissionRegistrar::class)))->not->toBeNull();
+
+    app(PermissionRegistrar::class)->initializeCache();
+
+    expect($reflectedProperty->getValue(app(PermissionRegistrar::class)))->toBeNull();
+});
+
+it('does not leak a previous tenant\'s permissions after switching cache context via initializeCache', function () {
+    // Two separate cache "stores" stand in for two tenants' cache namespaces
+    // (e.g. distinct cache prefixes/connections in a real multi-tenant app).
+    config([
+        'cache.stores.tenant_a' => ['driver' => 'array'],
+        'cache.stores.tenant_b' => ['driver' => 'array'],
+    ]);
+
+    // Insert both tenants' rows via the query builder, bypassing Eloquent,
+    // so the RefreshesPermissionCache model events don't auto-bust the cache and
+    // mask the very staleness this test is meant to catch.
+    $tenantAId = DB::table('permissions')->insertGetId([
+        'name' => 'tenant-permission',
+        'guard_name' => 'web',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    config(['permission.cache.store' => 'tenant_a']);
+    app(PermissionRegistrar::class)->initializeCache();
+
+    $loaded = app(PermissionRegistrar::class)->getPermissions()->firstWhere('name', 'tenant-permission');
+    expect($loaded->getKey())->toBe($tenantAId);
+
+    // Simulate switching to tenant B: its own row for the "same" permission has
+    // a different primary key, as it would in a separate tenant database.
+    DB::table('permissions')->where('id', $tenantAId)->delete();
+    $tenantBId = DB::table('permissions')->insertGetId([
+        'name' => 'tenant-permission',
+        'guard_name' => 'web',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+    expect($tenantBId)->not->toBe($tenantAId);
+
+    config(['permission.cache.store' => 'tenant_b']);
+    app(PermissionRegistrar::class)->initializeCache();
+
+    $loaded = app(PermissionRegistrar::class)->getPermissions()->firstWhere('name', 'tenant-permission');
+    expect($loaded->getKey())->toBe($tenantBId);
+});
+
 it('can check uids', function () {
     $uids = [
         // UUIDs