From a6fa3d4e3e19d8b01708fd92622d74cad16a7ec0 Mon Sep 17 00:00:00 2001 From: Chris Brown Date: Mon, 31 Jul 2023 14:47:47 -0400 Subject: [PATCH] [Docs] Sync doc updates across branches --- docs/advanced-usage/seeding.md | 10 ++++++--- docs/advanced-usage/testing.md | 2 +- docs/basic-usage/basic-usage.md | 2 +- docs/basic-usage/teams-permissions.md | 31 +++++++++++++++++++++++++++ 4 files changed, 40 insertions(+), 5 deletions(-) diff --git a/docs/advanced-usage/seeding.md b/docs/advanced-usage/seeding.md index d27bc2a1e..0f40e7f27 100644 --- a/docs/advanced-usage/seeding.md +++ b/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. diff --git a/docs/advanced-usage/testing.md b/docs/advanced-usage/testing.md index 8534a6319..45c8c843d 100644 --- a/docs/advanced-usage/testing.md +++ b/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. diff --git a/docs/basic-usage/basic-usage.md b/docs/basic-usage/basic-usage.md index 56bdd04d8..6903f3715 100644 --- a/docs/basic-usage/basic-usage.md +++ b/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(); diff --git a/docs/basic-usage/teams-permissions.md b/docs/basic-usage/teams-permissions.md index a97136e8c..d60657377 100644 --- a/docs/basic-usage/teams-permissions.md +++ b/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.