[Docs] Sync doc updates across branches

docs/advanced-usage/seeding.md

@@ -3,16 +3,18 @@ title: Database Seeding
 weight: 2
 ---
 
-## Flush cache before seeding
+## Flush cache before/after seeding
 
-You may discover that it is best to flush this package's cache before seeding, to avoid cache conflict errors. 
+You may discover that it is best to flush this package's cache **BEFORE seeding, to avoid cache conflict errors**.
+
+And if you use the `WithoutModelEvents` trait in your seeders, flush it **AFTER seeding as well**.
 
 ```php
 // reset cached roles and permissions
 app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();
 ```
 
-You can do this in the `SetUp()` method of your test suite (see the Testing page in the docs).
+You can optionally flush the cache before seeding by using the `SetUp()` method of your test suite (see the Testing page in the docs).
 
 Or it can be done directly in a seeder class, as shown below.
 
@@ -95,6 +97,8 @@ foreach ($permissionIdsByRole as $role => $permissionIds) {
  ])->toArray()
  );
 }
+
+// and also add the command to flush the cache again now after doing all these inserts
 ```
 
 **CAUTION**: ANY TIME YOU DIRECTLY RUN DB QUERIES you are bypassing cache-control features. So you will need to manually flush the package cache AFTER running direct DB queries, even in a seeder.

docs/advanced-usage/testing.md

@@ -55,5 +55,5 @@ However, if your application allows users to define their own roles and permissi
 
 With Laravel 7 you can simply create a model factory using the artisan command, and then call the `factory()` helper function to invoke it as needed.
 
-With Laravel 8 if you want to use the class-based Model Factory features you will need to `extend` this package's `Role` and/or `Permission` model into your app's namespace, add the `HasFactory` trait to it, and define a model factory for it. Then you can use that factory in your seeders like any other factory related to your app's models.
+With Laravel 8 if you want to use the class-based Model Factory features you will need to `extend` this package's `Role` and/or `Permission` model into your app's namespace, add the `HasFactory` trait to it, and define a model factory for it. Then you can use that factory in your seeders like any other factory related to your application's models.
 

docs/basic-usage/basic-usage.md

@@ -97,7 +97,7 @@ Since Role and Permission models are extended from Eloquent models, basic Eloque
 
 ```php
 $all_users_with_all_their_roles = User::with('roles')->get();
-$all_users_with_all_direct_permissions = User::with('permissions')->get();
+$all_users_with_all_their_direct_permissions = User::with('permissions')->get();
 $all_roles_in_database = Role::all()->pluck('name');
 $users_without_any_roles = User::doesntHave('roles')->get();
 $all_roles_except_a_and_b = Role::whereNotIn('name', ['role A', 'role B'])->get();

docs/basic-usage/teams-permissions.md

@@ -73,6 +73,37 @@ Role::create(['name' => 'reviewer']);
 
 The role/permission assignment and removal for teams are the same as without teams, but they take the global `team_id` which is set on login.
 
+## Changing The Active Team ID
+
+While your middleware will set a user's `team_id` upon login, you may later need to set it to another team for various reasons. The two most common reasons are these:
+
+### Switching Teams After Login
+If your application allows the user to switch between various teams which they belong to, you can activate the roles/permissions for that team by calling `setPermissionsTeamId($new_team_id)` and unsetting relations as described below.
+
+### Administrating Team Details
+You may have created a User-Manager page where you can view the roles/permissions of users on certain teams. For managing that user in each team they belong to, you must also use `setPermissionsTeamId($new_team_id)` to cause lookups to relate to that new team, and unset prior relations as described below.
+
+### Querying Roles/Permissions for Other Teams
+Whenever you switch the active `team_id` using `setPermissionsTeamId()`, you need to `unset` the user's/model's `roles` and `permissions` relations before querying what roles/permissions that user has (`$user->roles`, etc) and before calling any authorization functions (`can()`, `hasPermissionTo()`, `hasRole()`, etc).
+
+Example:
+```php
+// set active global team_id
+setPermissionsTeamId($new_team_id);
+
+// $user = Auth::user();
+
+// unset cached model relations so new team relations will get reloaded
+$user->unsetRelation('roles','permissions');
+
+// Now you can check:
+$roles = $user->roles;
+$hasRole = $user->hasRole('my_role');
+$user->hasPermissionTo('foo');
+$user->can('bar');
+// etc
+```
+
 ## Defining a Super-Admin on Teams
 
 Global roles can be assigned to different teams, and `team_id` (which is the primary key of the relationships) is always required.