Teams

https://github.com/jurager/teams
Admin
A Laravel package for managing teams and user permissions, featuring multi-tenant dynamic roles,...
Tokens:3,723
Snippets:14
Trust Score:7.4
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Run Jurager/Teams Installation Command

Source: https://github.com/jurager/teams/blob/3.0/README.md

Executes the `teams:install` Artisan command to set up the Jurager/Teams package. This command may overwrite existing data, so it is strongly recommended to perform backups before execution.

```Shell
php artisan teams:install
```

--------------------------------

### Install Jurager/Teams Composer Package

Source: https://github.com/jurager/teams/blob/3.0/README.md

Installs the Jurager/Teams Laravel package using Composer. This command adds the package to your project's dependencies, making its functionalities available for use.

```Shell
composer require jurager/teams
```

--------------------------------

### Creating a New Team and Assigning Roles with Permissions

Source: https://github.com/jurager/teams/blob/3.0/README.md

This example illustrates the process of programmatically creating a new team instance, saving it, and then assigning predefined roles (e.g., 'admin', 'user') to that team. Each role is associated with a detailed array of permissions, enabling granular access control for users assigned to these roles within the application.

```php
$team = new Team();

$team->name = 'Example Team';
$team->user_id = $user->id;

if ($team->save()) {

    $team->addRole('admin', [
        'employees.*',
        'sections.*',
        'articles.*',
        'tags.*',
        'comments.*',
        'team.edit',
        'stores.*',
        'plan.edit',
    ]);
    
    $team->addRole('user', [
        'employees.view',
        'articles.view',
        'articles.add',
        'sections.view',
        'sections.add',
        'comments.add',
        'tags.view',
        'stores.add',
        'stores.delete',
        'tags.add',
    ]);
}
```

--------------------------------

### Applying Role, Permission, and Ability Middleware to Routes

Source: https://github.com/jurager/teams/blob/3.0/README.md

This section demonstrates how to secure routes and route groups using the package's role, permission, and ability middleware. It illustrates various configurations, including passing team_id as a route parameter or directly within the middleware, and shows examples for implementing both 'OR' and 'AND' logic for multiple roles/permissions, as well as checking abilities on specific model instances.

```PHP
Route::group(['prefix' => 'admin', 'middleware' => ['role:admin,team_id']], function() {
    Route::get('/users', 'UserController@usersIndex');
    Route::get('/user/edit', ['middleware' => ['permission:edit-users,team_id'], 'uses' => 'UserController@userEdit']);
});
```

```PHP
Route::get('/{team_id}/users', ['middleware' => ['permission:views-users'], 'uses' => 'CommonController@commonUsers']);
```

```PHP
'middleware' => ['role:admin|root,{team_id}']
```

```PHP
'middleware' => ['role:admin|root,{team_id}']
// $user->hasTeamRole($team, ['admin', 'root']);

'middleware' => ['permission:edit-post|edit-user,{team_id}']
// $user->hasTeamPermission($team, ['edit-post', 'edit-user']);
```

```PHP
'middleware' => ['role:admin|root,{team_id},require']
// $user->hasTeamRole($team, ['admin', 'root'], require: true);

'middleware' => ['permission:edit-post|edit-user,{team_id},require']
// $user->hasTeamPermission($team, ['edit-post', 'edit-user'], require: true);
```

```PHP
'middleware' => ['ability:edit,App\Models\Article,{article_id}']
// $user->hasTeamAbility($team, 'edit', $article);
```

--------------------------------

### Run Laravel Database Migrations

Source: https://github.com/jurager/teams/blob/3.0/README.md

Executes all pending database migrations for the Laravel application, including those provided by the Jurager/Teams package. It's important to configure `config/teams.php` before running if custom table names or foreign keys are desired.

```Shell
php artisan migrate
```

--------------------------------

### Team Object API Reference

Source: https://github.com/jurager/teams/blob/3.0/README.md

Comprehensive API documentation for the `Team` object, typically accessed via `$user->team`. This section details various methods for managing team members, roles, abilities, groups, and invitations, including adding, updating, deleting, and querying team-related data.

```APIDOC
$team->owner
  - Description: Accesses the owner of the team.
  - Returns: User object of the team owner.

$team->users()
  - Description: Retrieves all users associated with the team, excluding the team owner.
  - Returns: Collection of User objects.

$team->allUsers()
  - Description: Retrieves all users associated with the team, including the team owner.
  - Returns: Collection of User objects.

$team->hasUser($user)
  - Description: Checks if a given user is a member of the team.
  - Parameters:
    - $user: User object to check.
  - Returns: Boolean (true if user is a member, false otherwise).

$team->addUser($user, $role_keyword)
  - Description: Adds a user to the team and assigns them a specified role by role ID or code.
  - Parameters:
    - $user: User object to add.
    - $role_keyword: Role ID or code to assign to the user.
  - Returns: Boolean (true on success, false otherwise).

$team->updateUser($user, $role_keyword)
  - Description: Updates the role of an existing user within the team.
  - Parameters:
    - $user: User object whose role is to be updated.
    - $role_keyword: New role ID or code to assign.
  - Returns: Boolean (true on success, false otherwise).

$team->deleteUser($user);
  - Description: Removes a specified user from the team.
  - Parameters:
    - $user: User object to remove.
  - Returns: Boolean (true on success, false otherwise).

$team->abilities()
  - Description: Retrieves all abilities associated with the team.
  - Returns: Collection of Ability objects.

$team->roles()
  - Description: Retrieves all roles defined within the team.
  - Returns: Collection of Role objects.

$team->userRole($user)
  - Description: Retrieves the role object assigned to a specific user within the team.
  - Parameters:
    - $user: User object to query.
  - Returns: Role object or null if no role is found for the user in this team.

$team->hasRole($role_keyword)
  - Description: Determines if the team has a specific role identified by its ID or code. If $role_keyword is null, checks if the team has any roles defined.
  - Parameters:
    - $role_keyword: Optional. Role ID or code to check for.
  - Returns: Boolean (true if role exists or any roles exist, false otherwise).

$team->getRole($role_keyword)
  - Description: Retrieves a specific role object from the team by its ID or code.
  - Parameters:
    - $role_keyword: Role ID or code to retrieve.
  - Returns: Role object or null if not found.

$team->addRole($code, $permissions, $name, $description)
  - Description: Adds a new role to the team with specified code, permissions, name, and description.
  - Parameters:
    - $code: Unique code for the new role.
    - $permissions: Array of permissions associated with the role.
    - $name: Display name for the role.
    - $description: Description of the role.
  - Returns: Role object of the newly created role.

$team->updateRole($role_keyword, $permissions, $name, $description)
  - Description: Updates an existing role in the team, identified by its keyword. Name and description are optional if no changes are needed.
  - Parameters:
    - $role_keyword: Role ID or code of the role to update.
    - $permissions: Array of new permissions for the role.
    - $name: Optional. New display name for the role.
    - $description: Optional. New description for the role.
  - Returns: Role object of the updated role.

$team->deleteRole($role_keyword)
  - Description: Deletes a specified role from the team.
  - Parameters:
    - $role_keyword: Role ID or code of the role to delete.
  - Returns: Boolean (true on success, false otherwise).

$team->groups()
  - Description: Retrieves all groups defined within the team.
  - Returns: Collection of Group objects.

$team->getGroup($group_keyword)
  - Description: Retrieves a specific group object from the team by its ID or code.
  - Parameters:
    - $group_keyword: Group ID or code to retrieve.
  - Returns: Group object or null if not found.

$team->addGroup($code, $permissions, $name)
  - Description: Adds a new group to the team with specified code, permissions, and name.
  - Parameters:
    - $code: Unique code for the new group.
    - $permissions: Array of permissions associated with the group.
    - $name: Display name for the group.
  - Returns: Group object of the newly created group.

$team->updateGroup($group_keyword, $permissions, $name)
  - Description: Updates an existing group in the team, identified by its keyword.
  - Parameters:
    - $group_keyword: Group ID or code of the group to update.
    - $permissions: Array of new permissions for the group.
    - $name: New display name for the group.
  - Returns: Group object of the updated group.

$team->deleteGroup($group_keyword)
  - Description: Deletes a specified group from the team.
  - Parameters:
    - $group_keyword: Group ID or code of the group to delete.
  - Returns: Boolean (true on success, false otherwise).

$team->hasUserWithEmail($email)
  - Description: Checks if any member of the team has the specified email address.
  - Parameters:
    - $email: Email address to check.
  - Returns: Boolean (true if a member with the email exists, false otherwise).

$team->userHasPermission($user, $permissions, $require)
  - Description: Checks if a specific user within the team possesses the given permissions. The `$require` parameter determines if all permissions in the array are needed (`true`) or if at least one is sufficient (`false`).
  - Parameters:
    - $user: User object to check.
    - $permissions: Array of permissions to verify.
    - $require: Boolean. If `true`, all permissions must be present; if `false`, at least one must be present.
  - Returns: Boolean (true if user has the required permissions, false otherwise).

$team->invitations()
  - Description: Retrieves all outstanding invitations for the team.
  - Returns: Collection of Invitation objects.
```

--------------------------------

### Team Authorization and Ability Access Logic

Source: https://github.com/jurager/teams/blob/3.0/README.md

This documentation details the underlying logic for determining access in team-based authorization and abilities. It outlines the different permission access levels and the step-by-step process for evaluating user permissions and abilities, including ownership checks, team-level permissions, and entity-specific rules.

```APIDOC
Access Levels:
  Permissions are governed by different access levels, which are compared to determine whether an action is allowed or forbidden. If the 'allowed' value is greater than or equal to the 'forbidden' value, the action is permitted.

  Level             | Value | Description
  ------------------|-------|----------------------------------------------------------------------------------------------
  `DEFAULT`         | 0     | Base level with no explicit permissions or restrictions.
  `FORBIDDEN`       | 1     | Base level denying access.
  `ROLE_ALLOWED`    | 2     | Permission granted based on the user's role in the team.
  `ROLE_FORBIDDEN`  | 3     | Restriction applied based on the user's role in the team.
  `GROUP_ALLOWED`   | 4     | Permission granted based on the user's group within the team.
  `GROUP_FORBIDDEN` | 5     | Restriction applied based on the user's group within the team.
  `USER_ALLOWED`    | 5     | Permission granted specifically for the user.
  `USER_FORBIDDEN`  | 6     | Restriction applied specifically to the user for this entity.
  `GLOBAL_ALLOWED`  | 6     | Global permissions applicable to the user regardless of the team context.

How Access Logic Works:
  1. Ownership Check: If the user is the owner of the entity (via isOwner), access is immediately granted.
  2. Team-Level Permission Check: The method checks:
     - Role-based permissions using `hasTeamPermission`.
     - Group-based permissions using `hasGroupPermission`.
     - Global permissions using `hasGlobalGroupPermissions`.
  3. Entity-Specific Rules: If the entity has specific rules (abilities), permissions and restrictions are evaluated for:
     - The user's role within the team.
     - The user's groups within the team.
     - The specific user assigned to this entity.
  4. Final Decision: If the final allowed level is greater than or equal to the forbidden level, access is granted.
```

--------------------------------

### Grant User Team Ability in PHP

Source: https://github.com/jurager/teams/blob/3.0/README.md

This code shows how to grant a user a new ability within a team. The `allowTeamAbility` method automatically creates the ability if it doesn't exist and allows specifying the target entity for the ability. If `$target_entity` is null, the ability defaults to the user.

```php
$user->allowTeamAbility($team, $action, $action_entity, $target_entity)
```

--------------------------------

### Managing Team Groups and User Attachments

Source: https://github.com/jurager/teams/blob/3.0/README.md

This section outlines the methods provided by the Jurager\Teams\Traits\HasTeams trait for comprehensive management of user groups within teams. It includes functionalities for adding, updating, deleting, retrieving, and checking the existence of groups, as well as attaching and detaching individual users from these groups.

```PHP
$team->addGroup($code, $permissions, $name)
```

```PHP
$team->updateGroup($group_keyword, $permissions, $name)
```

```PHP
$team->deleteGroup($group_keyword)
```

```PHP
$team->groups();
```

```PHP
$team->hasGroup($group_keyword)
```

```PHP
$group = $team->getGroup($group_keyword);
```

```PHP
$group->users();
```

```PHP
$group->attachUser($user);
```

```PHP
$group->detachUser($user);
```

--------------------------------

### Inspecting User Teams and Permissions with HasTeams Trait

Source: https://github.com/jurager/teams/blob/3.0/README.md

This snippet showcases various methods provided by the `Jurager\Teams\Traits\HasTeams` trait, allowing users to inspect their team memberships, ownership, roles, permissions, and abilities within the application. It covers accessing team lists, checking team affiliations, retrieving roles, and managing fine-grained permissions and abilities.

```php
// Access the teams that a user belongs to...
$user->teams

// Access all of a user's owned teams...
$user->ownedTeams

// Access all the team's (including owned teams) that a user belongs to...
$user->allTeams()

// Determine if a user owns a given team...
$user->ownsTeam($team)

// Determine if a user belongs to a given team...
$user->belongsToTeam($team)

// Get the role that the user is assigned on the team...
$user->teamRole($team)

// Determine if the user has the given role (or roles if array passed) on the given team...
// $require = true  (all roles in the array are required)
// $require = false  (only one or more role in the array are required)
$user->hasTeamRole($team, 'admin', $require)

// Access an array of all permissions a user has for a given team...
// Scope identifies which model to take permissions from, by default if null - getting all permissions ( ex. 'role', 'group')
$user->teamPermissions($team, $scope)

// Determine if a user has a given team permission or permissions if array passed...
// $require = true  (all permissions in the array are required)
// $require = false  (only one or more permission in the array are required)
// $scope - identifies in which model to check permissions, by default in all ( ex. 'role', 'group')
$user->hasTeamPermission($team, 'server:create', $require, $scope)

// Get list of abilities or forbidden abilities for users on certain model
$user->teamAbilities($team, $server)

// Determine if a user has a given ability on certain model...
$user->hasTeamAbility($team, 'server:edit', $server)

// Add an ability for user to action on certain model, if not found, will create a new one
$user->allowTeamAbility($team, 'server:edit', $server)

// Forbid an ability for user to action on certain model, used in case if global ability or role allowing this action
$user->forbidTeamAbility($team, 'server:edit', $server)
```

--------------------------------

### Check User Team Ability in PHP

Source: https://github.com/jurager/teams/blob/3.0/README.md

This snippet illustrates how to check if a user has a specific ability within a team context. The `hasTeamAbility` method evaluates various permission levels (role, group, user, global) to determine if the user can perform the specified action on a given entity.

```php
User::hasTeamAbility($team, 'edit_post', $post);
```

--------------------------------

### Integrate HasTeams Trait into Laravel User Model

Source: https://github.com/jurager/teams/blob/3.0/README.md

Adds the `HasTeams` trait from the Jurager/Teams package to your existing `User` model. This trait provides the necessary methods and relationships for enabling team management functionalities on the User model.

```PHP
<?php 

namespace App\Providers;

use Jurager\Teams\Traits\HasTeams;

class User extends Model {

    use HasTeams;
}
```

--------------------------------

### Check User Team Permission in PHP

Source: https://github.com/jurager/teams/blob/3.0/README.md

This snippet demonstrates how to verify if a user possesses a specific permission within the context of a team. It utilizes the `hasTeamPermission` method from the `Jurager\Teams\Traits\HasTeams` trait, which is crucial for granular authorization checks, typically within authorization policies.

```php
return $user->hasTeamPermission($team, 'server:update');
```

--------------------------------

### Forbidding a Team Ability for a User

Source: https://github.com/jurager/teams/blob/3.0/README.md

This method allows preventing a user from exercising a specific ability within a team, even if their assigned role would typically grant it. If the $target_entity is not provided, the ability target defaults to the user themselves.

```PHP
User::forbidTeamAbility($team, $action, $action_entity,$target_entity)
```
Tokens:
Raw