Fluentné buildery

Approvals::for(), as() a request() vracajú malé buildery, ktoré zbierajú kontext a nič nezapíšu až do terminálneho volania — approve(), reject(), ask(), cancel(), toggle(), close() alebo open(). Každé terminálne volanie prechádza cez ApprovalsManager, takže ho Approvals::fake() zaznamená. Tabuľky metód sú v časti Fasáda Approvals.

Pripojenie rozhodnutia ku konkrétnej žiadosti

Rozhodnutie sa predvolene pripojí k poslednej otvorenej žiadosti schvaľovaného modelu. within() ho pripne ku konkrétnej žiadosti — tá musí patriť schvaľovanému modelu a byť ešte otvorená, takže rozhodnutie o jednom modeli sa nikdy nezapočíta do žiadosti iného a nič neskončí v už uzavretom kole:

use RoundlyConsulting\Approvals\Facades\Approvals;

$request = Approvals::request($release)->from([$lead, $qa])->open();

Approvals::for($release)->as($lead)->within($request)->because('Ship it')->approve();

Approvals::for($otherRelease)->as($lead)->within($request)->approve();
// InvalidApprovalRequestException — the request belongs to another subject; nothing is written

// …later, once $request has resolved:
Approvals::for($release)->as($qa)->within($request)->reject();
// ClosedApprovalRequestException — its round is over; nothing is written

Pomocník approvals()

Globálny pomocník approvals() vráti ten istý singleton manažér — hodí sa tam, kde uprednostňujete funkciu pred fasádou:

approvals()->for($deployment)->as($user)->approve();   // the same manager as the facade

Approvals::as($user)->for($deployment)->approve();     // start from either side

Absolútna expirácia

expiresIn() prijíma počet sekúnd od teraz; expiringAt() ľubovoľnú inštanciu Carbon. Obe má builder rozhodnutia, builder žiadosti a od verzie 1.2.0 aj builder šablóny workflow:

use Carbon\CarbonImmutable;
use RoundlyConsulting\Approvals\Facades\Approvals;

Approvals::for($budget)->as($cfo)
    ->because('Within the quarterly limit')
    ->expiringAt(CarbonImmutable::parse('2026-12-31 23:59'))
    ->approve();

Neúplný builder

Terminálne metódy rozhodnutia potrebujú aktéra aj schvaľovaný model. Ak niektorý chýba, vznikne IncompletePendingApprovalException; hasPending() a close() potrebujú len schvaľovaný model — a close() aktéra odmietne:

use RoundlyConsulting\Approvals\Facades\Approvals;

Approvals::for($deployment)->approve();
// IncompletePendingApprovalException: No actor was set on the pending approval. Call as() first.

Nastavenia, ktoré volanie nevyužije

Každý setter niečo uloží, no nie každá terminálna metóda to má kam zapísať. Namiesto toho, aby nastavenie potichu zahodila, terminálna metóda, ktorá ho nevyužije, vyhodí InvalidApprovalRequestException ešte pred zápisom — takže ani Approvals::fake() nič nezaznamená:

use RoundlyConsulting\Approvals\Facades\Approvals;

// Taken: an ask's reason and its reply-by deadline
Approvals::for($post)->as($reviewer)->because('Check the sources')->expiresIn(86400)->ask();

// Refused with InvalidApprovalRequestException — nothing is written
Approvals::for($post)->as($reviewer)->weight(2)->ask();            // weightOnAsk: set the weight on the answer
Approvals::for($post)->as($reviewer)->expiresIn(3600)->reject();   // expiryOnReject: a rejection has no expiry
Approvals::for($post)->as($reviewer)->weight(2)->cancel();         // settingsOnCancel: a withdrawal records no decision
Approvals::for($purchase)->because('Withdrawn')->close();          // reasonOnClose: a round keeps no reason
Approvals::for($purchase)->as($admin)->close();                    // settingsOnClose: closing involves no actor

because() sa kontroluje prvé, takže close() s dôvodom aj ďalšími nastaveniami vyhodí reasonOnClose; aktér a schvaľovaný model buildera sa kontrolujú ešte skôr (IncompletePendingApprovalException). because(null) žiadny dôvod nenastaví a volanie bez nastavení funguje ako vždy. Tieto odmietnutia pribudli vo verzii 1.2.2 (váha pri ask(), dôvod pri close()) a 1.2.3 (ostatné) — predtým sa nastavenia potichu zahodili, takže kód, ktorý niektoré z nich nastavoval, teraz dostane výnimku: nastavenie, ktoré sa aj tak nikdy neuplatnilo, odstráňte.