Download the PHP package squareetlabs/laravel-teams-permissions without Composer

Squareetlabs/LaravelTeamsPermissions

A comprehensive Laravel package designed for advanced team-based permission management in multi-tenant applications based on [Jurager/Teams]. This package provides a flexible and powerful system for organizing users into teams, assigning granular permissions through roles and groups, and managing entity-specific access controls.

Core Functionality:

• Team Management: Create and manage teams with owners and members. Each team operates as an independent workspace with its own set of roles, permissions, and members.

• Role-Based Access Control (RBAC): Define custom roles for each team with specific permission sets. Roles can be assigned to users within a team, providing a flexible way to manage access levels. Team owners automatically have full access to all permissions.

• Permission System: Implement fine-grained permissions using a code-based system (e.g., posts.create, users.edit). Permissions are global entities that can be assigned to roles and groups across multiple teams. Supports wildcard permissions for flexible access patterns.

• Group Management: Organize users into groups within teams or globally. Groups can have their own permission sets, and permissions assigned to a group take precedence over individual user permissions within a team. This allows for efficient permission management when multiple users need the same access level.

• Global Groups: Create groups without team association to grant users access across all teams with the group's permissions. Perfect for scenarios like support teams, administrators, or auditors who need consistent access across multiple teams without being individually added to each one.

• Entity-Specific Abilities: Grant or deny permissions for specific model instances (e.g., allowing a user to edit a particular post but not others). This provides the most granular level of access control, enabling fine-tuned permissions for individual resources.

• Multi-Tenant Support: Built from the ground up for multi-tenant applications where each team represents a tenant. Teams are completely isolated, ensuring data security and access control between different tenants.

• Caching & Performance: Optional intelligent caching system to optimize permission checks, reducing database queries and improving application performance.

• Audit Logging: Optional comprehensive audit trail that logs all team-related actions including role assignments, permission changes, and member additions/removals.

• REST API: Optional complete REST API for team management, enabling frontend applications and third-party integrations to manage teams programmatically.

• Laravel Integration: Seamlessly integrates with Laravel's built-in authorization system, including Policies, Blade directives, and middleware for route protection.

Key Features

• ✅ Team Management: Create and manage teams with owners and members
• ✅ Roles & Permissions: Flexible role system with granular permissions
• ✅ Groups: Organize users into groups with shared permissions
• ✅ Abilities: Entity-specific permissions for individual models
• ✅ Smart Caching: Caching system to optimize permission checks
• ✅ Audit Logging: Complete action logging for teams (optional)
• ✅ REST API: Complete API for team management (optional)
• ✅ Blade Directives: Blade directives for permission checks in views
• ✅ Policies: Integration with Laravel's Policy system
• ✅ Rate Limiting: Protection against invitation spam
• ✅ Middleware: Middleware for route protection
• ✅ Artisan Commands: CLI tools for management

Requirements

• PHP >= 8.1
• Laravel 8.x, 9.x, 10.x, 11.x or 12.x

Installation

1. Install the Package

2. Publish Configuration and Migrations

This will publish:

• config/teams.php - Configuration file
• Database migrations

3. Configure the User Model

Add the HasTeams trait to your User model:

4. Run Migrations

⚠️ IMPORTANT: Always do backups before running migrations.

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

5. Optional Configuration

Enable Caching

To improve performance, enable caching in .env:

Enable Audit Logging

To log all team actions:

[!NOTE] If you enable audit logging after running migrations, you'll need to publish and run the audit migration:

Enable REST API

To expose a REST API for team management:

Configuration

The configuration file config/teams.php contains all options:

Custom Models

Cache

Audit

See config/teams.php for all available options.

Basic Usage

Creating a Team

Adding Roles and Permissions

Adding Team Members

Checking Permissions

Teams

Available Methods

Users

The HasTeams trait provides the following methods:

Roles & Permissions

Creating Roles with Permissions

Wildcard Permissions

You can use wildcards for permissions:

• posts.* - All permissions starting with posts.
• * - All permissions (if enabled in config)

Checking Permissions

Wildcard Permissions

You can enable wildcard permissions in configuration:

Users with these permissions will have full access to the team.

Abilities

Abilities allow specific permissions for individual entities.

Adding an Ability

Checking an Ability

Access Levels

Abilities use an access level system:

Access is granted if the allowed level >= forbidden level.

Groups

Groups allow organizing users with shared permissions.

Creating and Managing Groups

Global Groups

Groups without team_id are global and apply to all teams:

Middleware

The package provides middleware for route protection.

Configuration

Middleware is automatically registered as role, permission, and ability.

Usage in Routes

OR Operations

AND Operations

Blade Directives

The package includes Blade directives for permission checks in views:

Policies

The package integrates with Laravel's Policy system.

Generate a Policy

This generates a policy extending TeamPolicy:

Using the Policy

REST API

If you enable the REST API, you'll have access to complete endpoints for team management.

Enable API

Available Endpoints

Authentication

The API requires Sanctum authentication:

Artisan Commands

The package includes several useful commands:

Team Management

Permission Management

Utilities

Caching

The caching system significantly improves permission check performance.

Configuration

Clear Cache

Or programmatically:

Audit Logging

The audit system logs all important team actions.

Enable Audit

Audited Events

• role_assigned - Role assignment
• permission_granted - Permission granted
• permission_revoked - Permission revoked
• team_member_added - Member added
• team_member_removed - Member removed

Query Logs

[!NOTE] If you enable audit logging after running migrations, you'll need to run:

Events

The package fires events for important actions:

Available Events

• TeamCreating / TeamCreated
• TeamUpdating / TeamUpdated
• TeamDeleted
• TeamMemberAdding / TeamMemberAdded
• TeamMemberRemoving / TeamMemberRemoved
• TeamMemberUpdated
• TeamMemberInviting / TeamMemberInvited

Validation

The package includes validation rules:

Usage Examples

Blog System with Teams

Multi-tenant SaaS Application

Testing

The package includes factories and seeders for testing:

Troubleshooting

Error: "Model class for key user not found"

Make sure your User model is configured in config/teams.php:

Error: "AuditTableMissingException"

If you enable audit logging after running migrations:

Or disable audit logging in config/teams.php:

Cache Not Updating

Clear cache manually:

API Documentation

Classes and Methods

HasTeams Trait

Methods available on User model:

• ownsTeam(Team $team): bool - Check if user owns the team
• allTeams(): Collection - Get all teams (owned and belongs to)
• ownedTeams(): HasMany - Get teams user owns
• teams(): BelongsToMany - Get teams user belongs to
• belongsToTeam(Team $team): bool - Check if user belongs to team
• teamRole(Team $team): ?Role - Get user's role in team
• hasTeamRole(Team $team, string|array $roles, bool $require = false): bool - Check if user has role(s)
• teamPermissions(Team $team, ?string $scope = null): array - Get user's permissions for team
• hasTeamPermission(Team $team, string|array $permissions, bool $require = false, ?string $scope = null): bool - Check if user has permission(s)
• teamAbilities(Team $team, Model $entity, bool $forbidden = false): Collection - Get user's abilities for entity
• hasTeamAbility(Team $team, string $permission, Model $action_entity): bool - Check if user has ability
• allowTeamAbility(Team $team, string $permission, Model $action_entity, ?Model $target_entity = null): void - Allow ability
• forbidTeamAbility(Team $team, string $permission, Model $action_entity, ?Model $target_entity = null): void - Forbid ability
• deleteTeamAbility(Team $team, string $permission, Model $action_entity, ?Model $target_entity = null): void - Delete ability
• scopeWithTeamPermissions($query) - Eager load team permissions

HasMembers Trait

Methods available on Team model:

• owner(): BelongsTo - Get team owner
• users(): BelongsToMany - Get team members
• abilities(): HasMany - Get team abilities
• roles(): HasMany - Get team roles
• groups(): HasMany - Get team groups
• invitations(): HasMany - Get pending invitations
• allUsers(): Collection - Get all users including owner
• hasUser(User $user): bool - Check if user is member
• addUser(User $user, string $role_keyword): void - Add user to team
• updateUser(User $user, string $role_keyword): void - Update user's role
• deleteUser(User $user): void - Remove user from team
• inviteUser(string $email, int|string $keyword): void - Invite user by email
• inviteAccept(int $invitation_id): void - Accept invitation
• hasUserWithEmail(string $email): bool - Check if team has user with email
• userRole(User $user): ?Role - Get user's role in team
• userHasPermission(User $user, string|array $permissions, bool $require = false): bool - Check if user has permission
• hasRole(int|string|null $keyword = null): bool - Check if team has role
• getRole(int|string $keyword): ?Role - Get role by ID or code
• addRole(string $code, array $permissions, ?string $name = null, ?string $description = null): Role - Add role
• updateRole(int|string $keyword, array $permissions, ?string $name = null, ?string $description = null): Role - Update role
• deleteRole(int|string $keyword): bool - Delete role
• hasGroup(int|string|null $keyword = null): bool - Check if team has group
• getGroup(int|string $keyword): ?Group - Get group by ID or code
• addGroup(string $code, array $permissions = [], ?string $name = null): Group - Add group
• updateGroup(int|string $keyword, array $permissions = [], ?string $name = null): Group - Update group
• deleteGroup(int|string $keyword): bool - Delete group
• purge(): void - Delete team and all relations
• getPermissionIds(array $codes): array - Get permission IDs for codes

PermissionCache Service

• remember(string $key, callable $callback, ?int $ttl = null): mixed - Cache a value
• flush(): void - Flush all cache
• forget(string $key): void - Forget specific key
• get(string $key, mixed $default = null): mixed - Get cached value

AuditService Service

• log(string $action, mixed $team, mixed $user, mixed $subject = null, ?array $oldValues = null, ?array $newValues = null): void - Log audit event
• logRoleAssigned(mixed $team, mixed $user, mixed $role): void - Log role assignment
• logPermissionGranted(mixed $team, mixed $user, string $permission): void - Log permission granted
• logPermissionRevoked(mixed $team, mixed $user, string $permission): void - Log permission revoked
• logTeamMemberAdded(mixed $team, mixed $user, mixed $member, mixed $role): void - Log member added
• logTeamMemberRemoved(mixed $team, mixed $user, mixed $member): void - Log member removed

TeamPolicy Base Class

• checkTeamPermission(Model $user, Model $team, string $permission): bool - Check team permission
• checkTeamAbility(Model $user, Model $team, string $ability, Model $model): bool - Check team ability
• checkTeamRole(Model $user, Model $team, string|array $roles): bool - Check team role
• getTeamFromModel(Model $model): ?Model - Get team from model

Contributing

Contributions are welcome. Please:

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Changelog

See CHANGELOG.md for the full list of changes.

License

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

Support

For support, please open an issue on GitHub.

Authors

• Squareetlabs - [email protected]