Jurager Teams

The invitations table is always created by the migration process, even if the invitations.enabled configuration flag is set to false.

The invitations.enabled config flag only controls application-level logic, specifically:

• Route registration
• The behavior of inviteUser()
• The behavior of inviteAccept()

The Owner is a lightweight object, not a database-backed Eloquent model. It is returned by the teamRole() method when the queried user is the owner of the team. To distinguish an owner from a standard role in your code, use an instanceof check.

if ($role instanceof 
    \Jurager\Teams\Models\Owner
) {
    // The user is the team owner
}

if ($role instanceof \Jurager\Teams\Models\Owner) {
    // The user is the team owner
}

When implementing authorization logic (e.g., in Laravel Policies), prefer checking for specific permissions rather than checking for roles.

Checking permissions makes your code more resilient to changes in role names or structures. Checking roles couples your logic to specific role names, which is harder to maintain.

• Preferred: $user->hasTeamPermission($team, 'permission.code')
• Avoid: $user->hasTeamRole($team, 'role_name')

// Preferred — policy method
$user->hasTeamPermission($team, 'server:update');

// Avoid where possible — role check
$user->hasTeamRole($team, 'admin');

Jurager/Teams uses several key abstractions to manage access control within a Laravel application:

• Team: An isolated workspace containing members, roles, and groups.
• Role: A baseline set of permissions assigned to a user within a specific team (stored in team_user.role_id).
• Permission: A dot-notation string (e.g., articles.edit) that can be attached to either a Role or a Group.
• Group: An optional permission layer used to manage subsets of users within a team or across the entire application (global groups).
• Ability: An allow/forbid rule applied to a specific model instance. These are evaluated on top of existing role and group permissions.

A global group is a group where team_id = null. These groups are useful for cross-team roles (such as platform support staff) because they apply across all teams without requiring the user to be a member of every individual team.

Key Behaviors:

• Global group permissions are checked by hasGlobalGroupPermissions() during ability evaluation.
• They are evaluated only inside hasTeamAbility().
• They are not returned by $user->teamPermissions() and do not affect hasTeamPermission() checks.

// Creating a global group (no team scoping)
$group = Group::create(['code' => 'support-global', 'team_id' => null]);
$group->attachUser($user);

Permissions in Jurager/Teams are resolved through a hierarchy of four layers. Understanding the difference between hasTeamPermission() and hasTeamAbility() is critical for correct implementation:

Resolution Order

1. Role permissions: Applied to all team members assigned that role.
2. Group permissions: Overrides role access for members belonging to a specific group.
3. Global group permissions: Cross-team permissions for members of global groups.
4. Entity abilities: Instance-level allow/forbid rules applied to specific model records.

Method Selection

• Use hasTeamPermission() when you only need to check Layers 1 and 2 (Role and Group permissions).
• Use hasTeamAbility() when you need to evaluate all four layers, including instance-level entity abilities.

Groups act as an override layer on top of standard team role permissions. They allow you to grant or deny specific abilities to subsets of users within a team.

• If a user has a team permission, but their group forbids an action, the action is denied.
• If a user lacks a team permission, but their group allows an action, the action is allowed.

Important Constraints:

• Group rules only affect hasTeamAbility() checks. They do not affect plain hasTeamPermission() checks.
• Group permissions participate in ability level comparison (refer to the Abilities documentation for details).

To allow your User model to interact with teams, add the HasTeams trait to your User class.

use Jurager\
Teams\\Traits\\HasTeams;

class User extends Authenticatable
{
    use HasTeams;
}