Download the PHP package jurager/teams without Composer

Jurager/Teams

Laravel package to manage teams and operate with user permissions, abilities, supporting multi-tenant dynamic roles, roles groups, capabilities, and permissions for each team.

Users in teams can be combined into groups, with their own abilities, access rights given to a user group overrides the rights granted to a user in a team.

You can add a user to a global group to grant them access to all teams with the group's permissions. This feature is handy when you want to, for instance, provide support for all teams without assigning the user to created teams.

[!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
• Installation
• Actions
• Teams
• Users
• Groups
  • Scope of Use
  • Groups Managing
  • Groups Permissions
• Roles & Permissions
  • Authorization
• Abilities
  • Adding an Ability
  • Checking an Ability
  • Forbidding an Ability
  • Creating Abilities
• Middlewares
  • Middleware Configuration
  • Middleware Routes
  • Middleware Usage
• License

Requirements

PHP >= 8.1 and Laravel 8.x or higher

Installation

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

Run the migrations

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

To complete the installation process add the TeamPolicy to your existing AuthServiceProvider

Actions

Actions are predefined code blocks provided by the package to simplify common tasks in your application. Found in the app/Actions/Teams directory, these blocks can be easily invoked when users perform specific actions. They offer a quick way to implement functionality without starting from scratch. You can also customize or extend these actions to fit your needs precisely.

Explore the available actions and adapt them as necessary to maintain a clean and efficient codebase, speeding up your development process.

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.

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.

Groups

Users within teams can be organized into groups, each with its own set of permissions.

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

Scope of Use

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

• A user can't server:edit within 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:

Groups Permissions

You can manage permissions within a group using the following methods:

[!NOTE] Team groups work together with abilities, so you should use ability checking methods to determine if users have specific access rights within groups.

Middleware ability is used to check the user's rights within the team group during requests to your application

Refer to the middlewares section in the documentation for more information.

Roles & Permissions

Roles and permissions provide a flexible way to manage access control within your application. Each team member added to a team can be assigned a role, and each role is associated with a set of permissions.

These roles and permissions are stored in your application's database, allowing for dynamic management of access control. This enables features like role and permission management within your application's administration pages.

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 capabilities that define what actions users with that role can perform within the application. These capabilities are stored in the database and can be managed dynamically.

The second argument for $team->addRole() is an array of capabilities, 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, it's unnecessary to check a user's role directly. Instead, focus on verifying specific granular permissions. Roles primarily serve as a way to group granular permissions for organizational purposes. Typically, you'll execute calls to this method within your application's authorization policies.

This example demonstrates how to check if a user within a team has permission to update a server. Adjust the parameters according to your application's specific requirements and use cases.

Abilities

Adding abilities to users is straightforward. You don't need to create a role or an ability beforehand.

Simply pass the name of the ability, and the package will create it if it's not already existing.

Adding an Ability

To add the ability to edit an article within a team for a specific user, you need to provide the entity, such as the article object, and the team object:

Checking an Ability

To check if a user has a specific ability in a team, you can use the following method:

Forbidding an Ability

If you need to forbid a user from having a certain ability for instance, if the role abilities allow this ability, you can do so using the following method:

Creating Abilities

If you need to create abilities without attaching them to a user, you can use the Ability model provided by this package.

This model is published during installation, allowing you to create abilities separately:

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 an 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.