Žiadosti o pripojenie

Opak pozvánok: používateľ požiada o vstup do tímu a admin žiadosť schváli alebo zamietne. Či tím žiadosti vôbec prijíma, určuje jeho nastavenie JoinPolicy, nie is_public — is_public je len príznak pre vyhľadávanie cez Team::query()->public(), takže aj súkromný tím žiadosti prijíma, pokiaľ nie je len na pozvánky:

use RoundlyConsulting\Teams\Facades\Teams;

$requests = Teams::for($team)->joinRequests();

$request = $requests->open($user, requestedRole: 'member', message: 'Please add me');

$requests->approve($request, by: $admin);                  // Member — adds the requester
$requests->approve($request, by: $admin, role: 'editor');  // override the role
$requests->deny($request, by: $admin);                     // JoinRequest — no membership

$requests->pending();                                      // Collection<JoinRequest>

Žiadosť je idempotentná — druhé volanie pre ten istý tím a žiadateľa vráti existujúcu čakajúcu žiadosť. Pri vytvorení žiadosti sa spustí JoinRequestCreated. open() prijme aj meta a termín:

$request = Teams::for($team)->joinRequests()->open(
    $user,
    requestedRole: 'member',
    message: 'Please add me',
    meta: ['source' => 'web'],
);

Žiadosť o pripojenie je pre nováčikov: open() vyhodí TeamsException, ak žiadateľ už má aktívne členstvo. Rolu zmeníte cez members()->changeRole().

Schválenie a zamietnutie

• Schválenie pridá žiadateľa ako člena, označí žiadosť ako Approved, zapíše responded_by a responded_at a spustí JoinRequestApproved.
• Rola sa určí z roly zadanej schvaľovateľom, potom zo žiadanej roly, potom z nastavenia tímu DefaultMemberRole a nakoniec z roles.default (member).
• Žiadateľ, ktorý sa medzitým pridal (napríklad cez pozvánku), si členstvo ponechá nezmenené; schválenie len uzavrie žiadosť.
• Zamietnutie označí žiadosť ako Denied, zapíše schvaľovateľa a spustí JoinRequestDenied — členstvo nevznikne.
• Schválenie či zamietnutie žiadosti iného tímu cez Teams::for($team) vyhodí JoinRequestNotFoundException.

Vybavená žiadosť je konečná. Schválenie alebo zamietnutie žiadosti, ktorá už nečaká (bola schválená, zamietnutá alebo vypršala, aj keď ju súčasne vybavil niekto iný), vyhodí JoinRequestNotPendingException a nič nezmení, takže stará žiadosť nikdy znova nepridá odobratého člena. Prechod z čakajúcej na vybavenú je jediný podmienený update, takže z dvoch súbežných schvaľovateľov vyhrá práve jeden; schválenie, ktoré odmietne limit miest, nechá žiadosť čakať:

use RoundlyConsulting\Teams\Exceptions\JoinRequestNotPendingException;
use RoundlyConsulting\Teams\Facades\Teams;

try {
    Teams::for($team)->joinRequests()->approve($request, by: $admin);
} catch (JoinRequestNotPendingException) {
    // "Join request #42 has already been resolved." — nothing changed
}

Pravidlá vstupu

Čo sa s novou žiadosťou stane, určuje pravidlo vstupu tímu: tím len na pozvánky ju odmietne výnimkou TeamsException a predvolené pravidlo Request ju nechá čakať. Otvorený tím žiadosť automaticky schváli s predvolenou rolou tímu (DefaultMemberRole, potom roles.default) — nikdy nie s rolou, o ktorú žiadateľ požiadal; žiadosť o inú rolu čaká na vlastníka či admina a rovnako každá žiadosť, kým sa vyžaduje schválenie. Pozrite Nastavenia tímu.

Žiadosti s termínom

Parametrom expiresAt nastavíte termín; null (predvolene) nevyprší nikdy. Teams::joinRequests()->expire() — alebo teams:join-requests:prune — automaticky zamietne čakajúce žiadosti po termíne — použije stav Denied bez schvaľovateľa (rozhodnutie systému) a spustí JoinRequestExpired:

use RoundlyConsulting\Teams\Facades\Teams;
use RoundlyConsulting\Teams\Models\JoinRequest;

$request = Teams::for($team)->joinRequests()->open($user, requestedRole: 'member', expiresAt: now()->addDays(14));

$request->isExpired();                    // true once the deadline passes
JoinRequest::query()->expiredPending();   // pending requests past their expiry

Teams::joinRequests()->expire();          // int — auto-decline them now

use Illuminate\Support\Facades\Schedule;

// routes/console.php
Schedule::command('teams:join-requests:prune')->daily();   // auto-decline + JoinRequestExpired
Schedule::command('model:prune')->daily();                 // hard-delete long-resolved rows

JoinRequest je Prunable: php artisan model:prune natrvalo zmaže vybavené žiadosti, ktorých posledná zmena je staršia ako join_requests.prune_after (30 dní). Čakajúce žiadosti sa nemažú nikdy.

Model JoinRequest

$request->status;           // JoinRequestStatus::Pending | Approved | Denied
$request->isPending();      // bool
$request->requester;        // who asked (MorphTo)
$request->respondedBy;      // who decided (MorphTo) — null for a system decline
$request->responded_at;     // ?Carbon
$request->requested_role;   // ?string
$request->message;          // ?string
$request->meta;             // Collection

Enum stavov

JoinRequestStatus je enum s reťazcovými hodnotami — pending, approved, denied — s pomocníkmi z enums-for-laravel pre selecty a validáciu. Expirovaná žiadosť sa zapíše ako Denied, nemá vlastný stav:

use RoundlyConsulting\Teams\Enums\JoinRequestStatus;

JoinRequestStatus::options();          // Collection<EnumOption> (value, label, name) for selects
JoinRequestStatus::labels();           // Collection: 'Pending', 'Approved', 'Denied'
JoinRequestStatus::validationRule();   // 'in:pending,approved,denied'
JoinRequestStatus::tryFromLabel('Approved');