Laravel Jetstream Teams

--teams 옵션을 사용하여 제트스트림(Jetstream)을 설치한 경우, 애플리케이션은 팀 생성 및 관리를 지원하도록 구조화될 것입니다.

제트스트림의 팀 기능은 각 등록된 사용자가 여러 팀을 생성하고 소속될 수 있도록 합니다. 기본적으로 모든 등록된 사용자는 "Personal" 팀에 속하게 됩니다. 예를 들어, "Sally Jones"라는 이름의 사용자가 새 계정을 생성하면 "Sally's Team"이라는 팀에 할당됩니다. 등록 후 사용자는 이 팀의 이름을 변경하거나 추가 팀을 생성할 수 있습니다.

제트스트림의 팀 구조화와 방식이 모든 애플리케이션에 적합하지 않을 수 있습니다. 사용 사례에 맞지 않는다면, 팀 기반의 제트스트림 애플리케이션이 아닌 애플리케이션을 생성하고 자신의 필요에 따라 수동으로 팀 기능을 추가하는 것도 좋습니다.

Team Creation

팀 생성 뷰는 오른쪽 상단의 사용자 탐색 드롭다운 메뉴를 통해 접근할 수 있습니다.

Actions

다른 많은 제트스트림 기능과 마찬가지로, 팀 생성 및 삭제 로직은 앱의 `app/Actions/Jetstream` 디렉토리 내의 관련 액션 클래스를 수정함으로써 사용자 정의할 수 있습니다. 이 액션에는 `CreateTeam`, `UpdateTeamName`, `DeleteTeam`이 포함됩니다. 이러한 각 액션은 애플리케이션의 UI에서 사용자가 해당 작업을 수행할 때 호출됩니다. 애플리케이션의 필요에 따라 이러한 액션을 자유롭게 수정할 수 있습니다.

Views/Pages

Livewire 스택을 사용하는 경우, 팀 생성 뷰는 `resources/views/teams/create-team-form.blade.php` Blade 템플릿을 사용하여 표시됩니다. Inertia 스택을 사용하는 경우, 이 뷰는 `resources/js/Pages/Teams/CreateTeamForm.vue` 템플릿을 사용하여 표시됩니다. 팀 생성 양식에 지정된 추가 입력 필드는 사용자가 팀을 생성할 때 `App\Actions\Jetstream\CreateTeam` 액션 클래스에 제공됩니다.

 

Inspecting User Teams

사용자의 팀에 대한 정보는 `Laravel\Jetstream\HasTeams` 트레이트에 의해 제공되는 메소드를 통해 접근할 수 있습니다. 이 트레이트는 제트스트림의 설치 중에 자동적으로 애플리케이션의 `App\Models\User` 모델에 적용됩니다. 이 트레이트는 사용자의 팀을 조사할 수 있는 다양한 유용한 메소드를 제공합니다:

// Access a user's currently selected team...
$user->currentTeam : Laravel\Jetstream\Team

// Access all of the team's (including owned teams) that a user belongs to...
$user->allTeams() : Illuminate\Support\Collection

// Access all of a user's owned teams...
$user->ownedTeams : Illuminate\Database\Eloquent\Collection

// Access all of the teams that a user belongs to but does not own...
$user->teams : Illuminate\Database\Eloquent\Collection

// Access a user's "personal" team...
$user->personalTeam() : Laravel\Jetstream\Team

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

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

// Get the role that the user is assigned on the team...
$user->teamRole($team) : \Laravel\Jetstream\Role

// Determine if the user has the given role on the given team...
$user->hasTeamRole($team, 'admin') : bool

// Access an array of all permissions a user has for a given team...
$user->teamPermissions($team) : array

// Determine if a user has a given team permission...
$user->hasTeamPermission($team, 'server:create') : bool

 

The Current Team

제트스트림 애플리케이션 내의 모든 사용자는 "current team"을 가지고 있습니다. 이는 사용자가 활성적으로 리소스를 보고 있는 팀입니다. 예를 들어, 당신이 캘린더 애플리케이션을 구축하고 있다면, 애플리케이션은 사용자의 현재 팀에 대한 다가오는 캘린더 이벤트를 표시할 것입니다.

사용자의 현재 팀은 `$user->currentTeam` Eloquent 관계를 사용하여 접근할 수 있습니다. 이 관계는 다른 Eloquent 쿼리를 사용자의 현재 팀으로 범위 지정하는 데 사용할 수 있습니다:

use App\Models\Calendar;

return Calendar::where(
    'team_id', $request->user()->currentTeam->id
)->get();

 

사용자는 제트스트림 탐색 바 내에 있는 "팀 전환" 메뉴를 통해 자신의 현재 팀을 전환할 수 있습니다.

 

The Team Object

`$user->currentTeam` 또는 제트스트림의 다른 팀 관련 Eloquent 쿼리를 통해 접근하는 팀 객체는 팀의 속성과 관계를 조사하기 위한 다양한 유용한 메소드를 제공합니다:

// Access the team's owner...
$team->owner : App\Models\User

// Get all of the team's users, including the owner...
$team->allUsers() : Illuminate\Database\Eloquent\Collection

// Get all of the team's users, excluding the owner...
$team->users : Illuminate\Database\Eloquent\Collection

// Determine if the given user is a team member...
$team->hasUser($user) : bool

// Determine if the team has a member with the given email address...
$team->hasUserWithEmail($emailAddress) : bool

// Determine if the given user is a team member with the given permission...
$team->userHasPermission($user, $permission) : bool

 

Member Management

팀 멤버는 제트스트림의 "Team Settings" 뷰를 통해 팀에 추가되거나 제거될 수 있습니다. 기본적으로, 팀 멤버십을 관리할 수 있는 것은 팀 소유자뿐입니다. 이 제한은 `App\Policies\TeamPolicy` 클래스에서 정의됩니다. 당연히, 이 정책은 필요에 따라 자유롭게 수정할 수 있습니다.

Member Management Actions

다른 제트스트림 기능의 사용자 정의 과정과 마찬가지로, 팀 멤버 추가 로직은 `App\Actions\Jetstream\AddTeamMember` 액션 클래스를 수정함으로써 사용자 정의할 수 있습니다. 이 클래스의 `add` 메소드는 현재 인증된 사용자, `Laravel\Jetstream\Team` 인스턴스, 팀에 추가되는 사용자의 이메일 주소, 그리고 팀에 추가되는 사용자의 역할(해당되는 경우)과 함께 호출됩니다.

이 액션은 사용자를 실제로 팀에 추가할 수 있는지 검증한 후 사용자를 팀에 추가하는 책임이 있습니다. 이 액션은 특정 애플리케이션의 필요에 따라 사용자 정의할 수 있습니다.

팀 멤버 제거는 `App\Actions\Jetstream\RemoveTeamMember` 액션 클래스를 수정함으로써 사용자 정의할 수 있습니다.

Member Management Views/Pages

Livewire 스택을 사용하는 경우, 팀 멤버 관리자 뷰는 `resources/views/teams/team-member-manager.blade.php` Blade 템플릿을 사용하여 표시됩니다. Inertia 스택을 사용하는 경우, 이 뷰는 `resources/js/Pages/Teams/TeamMemberManager.vue` 템플릿을 사용하여 표시됩니다. 일반적으로 이러한 템플릿은 사용자 정의가 필요하지 않습니다.

Invitaions

기본적으로 제트스트림은 지정한 기존 애플리케이션 사용자를 팀에 단순히 추가합니다. 그러나 많은 애플리케이션은 팀에 초대된 사용자에게 초대 이메일을 보내기로 선택합니다. 사용자가 계정이 없는 경우, 초대 이메일은 계정을 생성하고 초대를 수락하도록 지시할 수 있습니다. 또는 사용자가 이미 계정이 있는 경우, 초대를 수락하거나 무시할 수 있습니다.

다행히도, 제트스트림은 몇 줄의 코드만으로 애플리케이션에 팀 멤버 초대 기능을 활성화할 수 있도록 합니다. 시작하려면, 애플리케이션의 "팀" 기능을 활성화할 때 invitations 옵션을 전달하세요. 이는 애플리케이션의 `config/jetstream.php` 설정 파일의 features 배열을 수정하여 수행할 수 있습니다:

 

use Laravel\Jetstream\Features;

'features' => [
    Features::termsAndPrivacyPolicy(),
    Features::profilePhotos(),
    Features::api(),
    Features::teams(['invitations' => true]),
    Features::accountDeletion(),
],

 

제트스트림의 초대 기능을 활성화하면, 팀에 초대된 사용자는 팀 초대를 수락하기 위한 링크가 포함된 초대 이메일을 받게 됩니다. 사용자는 초대를 수락할 때까지 팀의 정식 멤버가 되지 않습니다.

 

Invitation Actions

사용자가 팀에 초대되면, 애플리케이션의 `App\Actions\Jetstream\InviteTeamMember` 액션은 현재 인증된 사용자, 새 사용자가 초대된 팀, 초대된 사용자의 이메일 주소, 그리고 선택적으로 팀에 가입하면 할당되어야 할 역할과 함께 호출됩니다. 이 액션을 검토하거나 애플리케이션의 필요에 따라 수정할 수 있습니다.

팀 초대 기능을 사용하기 전에, 라라벨 애플리케이션이 이메일을 보낼 수 있도록 구성되어 있는지 확인해야 합니다. 그렇지 않으면, 라라벨은 애플리케이션 사용자에게 팀 초대 이메일을 보낼 수 없습니다.

Roles/Permissions

팀에 추가된 각 팀 멤버는 주어진 역할을 할당받을 수 있으며, 각 역할은 일련의 권한을 할당받습니다. 역할 권한은 애플리케이션의 `App\Providers\JetstreamServiceProvider` 클래스에서 `Jetstream::role` 메소드를 사용하여 정의됩니다. 이 메소드는 역할의 "slug", 사용자 친화적인 역할 이름, 역할 권한, 그리고 역할에 대한 설명을 받습니다. 이 정보는 팀 멤버 관리 뷰에서 역할을 표시하는 데 사용됩니다.

예를 들어, 라라벨 Forge와 같은 서버 관리 애플리케이션을 구축한다고 상상해 보세요. 우리는 애플리케이션의 팀 역할을 다음과 같이 정의할 수 있습니다:

 

Jetstream::defaultApiTokenPermissions(['read']);

Jetstream::role('admin', 'Administrator', [
    'server:create',
    'server:read',
    'server:update',
    'server:delete',
])->description('Administrator users can perform any action.');

Jetstream::role('support', 'Support Specialist', [
    'server:read',
])->description('Support specialists can read server information.');

 

팀 지원으로 제트스트림이 설치되면, 사용 가능한 API 권한은 역할에 사용 가능한 모든 고유 권한을 결합하여 자동으로 파생됩니다. 따라서 `Jetstream::permissions` 메소드에 대한 별도의 호출은 필요하지 않습니다.

Authorization

물론, 팀 멤버가 발신한 요청이 해당 사용자에 의해 실제로 수행될 수 있음을 인증할 방법이 필요할 것입니다. 사용자의 팀 권한은 `Laravel\Jetstream\HasTeams` 트레이트를 통해 사용할 수 있는 `hasTeamPermission` 메소드를 사용하여 조사할 수 있습니다.

사용자의 역할을 조사할 필요는 일반적으로 없습니다. 사용자가 주어진 세부적인 권한을 가지고 있는지만 조사하면 됩니다. 역할은 단순히 세부 권한을 그룹화하는 데 사용되는 표현적인 개념입니다. 일반적으로, 이 메소드에 대한 호출은 애플리케이션의 인증 정책 내에서 실행됩니다:

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

 

Combining Team Permissions With API Permissions

API 지원과 팀 지원을 모두 제공하는 제트스트림 애플리케이션을 구축할 때는, 애플리케이션의 인증 정책 내에서 들어오는 요청의 팀 권한과 API 토큰 권한을 검증해야 합니다. 이는 API 토큰이 이론적으로 행동을 수행할 수 있는 능력을 가질 수 있지만, 사용자가 실제로 해당 행동을 팀 권한을 통해 부여받지 않았을 수 있기 때문에 중요합니다:

/**
 * Determine whether the user can view a flight.
 */
public function view(User $user, Flight $flight): bool
{
    return $user->belongsToTeam($flight->team) &&
           $user->hasTeamPermission($flight->team, 'flight:view') &&
           $user->tokenCan('flight:view');
}