Download the PHP package jurager/teams without Composer

Jurager/Teams

A Laravel package for managing teams and user permissions, supporting multi-tenant dynamic roles, role groups, and team-specific permissions.

Users can be organized into groups within teams, each with custom permissions and abilities. Permissions assigned to a user group override individual user permissions within a team.

Additionally, users can be added to a global group to grant them access across all teams with the group’s permissions. This feature is ideal for scenarios like providing support across multiple teams without the need to add users to each team individually.

[!NOTE] The documentation for this package is currently being written. For now, please refer to this readme for information on the functionality and usage of the package.

• Requirements
• Schema
• Installation
• Teams
• Users
• Roles & Permissions
  • Authorization
• Abilities
  • Adding an Ability
  • Checking an Ability
  • Access Levels
  • How Access Logic Works
  • Forbidding an Ability
• Groups
  • Usage Scope
  • Groups Managing
  • Groups Abilities
• Middlewares
  • Middleware Configuration
  • Middleware Routes
  • Middleware Usage
• License

Requirements

PHP >= 8.1 and Laravel 8.x or higher

Schema

Installation

Always do backups, next command may overwrite your actual data.

Run the migrations

[!NOTE] If you wish to use custom foreign keys and table names, make changes to config config/teams.php before running migrations.

Then, add the HasTeams trait to your existing User model.

Teams

A team can be accessed via $user->team, providing methods for inspecting the team's attributes and relations:

These methods allow you to efficiently manage and interact with teams, including roles, users, permissions, and invitations.

[!NOTE] By default, the package uses the built-in model. If you want to use your own model, or specify a custom table name in the database, use the settings in the configuration file - teams.models.team, teams.tables.teams, teams.foreign_keys.team_id

Users

The Jurager\Teams\Traits\HasTeams trait provides methods to inspect a user's teams:

These methods enable you to efficiently manage and inspect a user's teams, roles, permissions, and abilities within your application.

Roles & Permissions

Roles and permissions offer a flexible approach to managing access control within your application. Each team member can be assigned a role, with each role tied to a specific set of permissions. These roles and permissions are stored in your application's database, allowing for dynamic and easy management of access and enables features like role and permission management through your application's admin interface.

Example: Creating a New Team with Roles and Permissions

In the above example, we create a new team and assign it two roles: "admin" and "user". Each role is associated with a set of permissions that define what actions users with that role can perform within the application.

The second argument for $team->addRole() is an array of permissions, which determine the actions that users with the corresponding role can perform in the application.

Authorization

To ensure that incoming requests initiated by a team member can be executed by that user, the application needs to verify the permissions of the user's team. This verification can be done using the hasTeamPermission method, which is available through the Jurager\Teams\Traits\HasTeams trait.

[!NOTE]
In most cases, checking a user's role is often unnecessary. Instead, prioritize verifying specific granular permissions, as roles mainly serve to group these permissions for organizational clarity. Typically, you’ll use this approach within your application's authorization policies.

Example: Check if a user within a team has permission to update a server

Abilities

Abilities - enables users to perform specific actions on application entities or models. For example, you can grant a user within a team the ability to edit posts.

Adding an Ability

Adding abilities to users is easy — just pass the ability name, and it’ll be created automatically if it doesn’t exist.

To grant a user the ability to edit an article within a team, simply provide the relevant entities, such as the article and team objects:

Checking an Ability

To verify if a user has a specific ability within the context of a team, based on various permission levels (role, group, user, and global), you can use the following method:

This method checks if the user can perform the specified ability (e.g., 'edit_post') on the given entity (e.g., a post) within the context of the specified team. It takes into account the user's role, groups, global permissions, and any entity-specific access rules.

Access Levels

Permissions are governed by different access levels, which are compared to determine whether an action is allowed or forbidden. There are two key indicators:

• allowed: The highest permission level granted to the user.
• forbidden: The highest restriction applied to the user.

If the allowed value is greater than or equal to the forbidden value, the action is permitted.

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.

Forbidding an Ability

To prevent a user from having a specific ability (even if their role allows it), use the following method:

Groups

Users within teams can be organized into groups, each with its own set of abilities and permissions. Groups work together with abilities and permissions, so you should use ability and permission checking methods to determine if users have specific access rights within groups.

[!NOTE]
Access rights granted to a group of users take precedence over rights granted to a user within role in a team.

Usage Scope

• User can server:edit in the team, but is part of a group restricted from server:edit for specific entities.

• User can't server:edit in the team, but is in a group permitted to server:edit specific entities.

Groups Managing

The Jurager\Teams\Traits\HasTeams trait provides methods to inspect a user's team groups:

Middlewares

Middleware Configuration

The middleware provided by this package is automatically registered as role, permission, and ability.

However, if you wish to use your own customized middlewares, you can modify the middleware.register in the config/teams.php.

Middleware Routes

You can use middleware to filter routes and route groups based on permissions or roles.

[!NOTE]
Consider, that team_id represents the actual ID of the team in the database.

If you need to customize the name of this variable, adjust the foreign_keys.team_id value in your config/teams.php file to match your database structure.

[!NOTE]
Middleware logic may vary based on how you pass the {team_id} variable.

• You can pass the {team_id} variable as a route parameter:

• You can pass the {team_id} variable directly as a middleware option:

• You can send the {team_id} variable with each request type (GET/POST/PUT, etc.).

Middleware Usage

For OR operations, use the pipe symbol:

For AND functionality:

To check the ability to perform a specific action on a specific model item, use the ability middleware:

In this case, pass {article_id} as a request parameter or route parameter to allow the package to identify the model object.

License

This package is open-sourced software licensed under the MIT license.