Akcie a DTO

Akcie v RoundlyConsulting\Approvals\Actions sú kód, ktorý spúšťa fasáda aj manažér — jednoúčelové triedy s metódou execute(), ktoré skladáte do vlastných akcií, jobov a príkazov. Mapu metód fasády na akcie nájdete v časti DI a akcie.

Signatúry akcií

use RoundlyConsulting\Approvals\Actions\ApproveAction;
use RoundlyConsulting\Approvals\Actions\CancelApprovalAction;
use RoundlyConsulting\Approvals\Actions\CloseApprovalRequestAction;
use RoundlyConsulting\Approvals\Actions\ExpireApprovalsAction;
use RoundlyConsulting\Approvals\Actions\RejectAction;
use RoundlyConsulting\Approvals\Actions\RequestApprovalAction;
use RoundlyConsulting\Approvals\Actions\ToggleApprovalAction;
use RoundlyConsulting\Approvals\DataTransferObjects\DecisionData;
use RoundlyConsulting\Approvals\Enums\ApprovalStatus;

app(ApproveAction::class)->execute($user, $post, DecisionData::approved('Looks good'));
app(RejectAction::class)->execute($user, $post, DecisionData::rejected('Needs work'));
app(RequestApprovalAction::class)->execute($user, $post);                    // pending Approval
app(RequestApprovalAction::class)->execute($user, $post, new DecisionData(ApprovalStatus::Pending, 'Check the sources', now()->addDay()));
app(CancelApprovalAction::class)->execute($user, $post, 'Changed my mind');   // ?Approval
app(ToggleApprovalAction::class)->execute($user, $post);                     // bool
app(ToggleApprovalAction::class)->execute($lead, $release, DecisionData::approved('LGTM'), $request);
app(CloseApprovalRequestAction::class)->execute($purchase);                  // int — rounds closed, as cancelled
app(CloseApprovalRequestAction::class)->execute($purchase, ApprovalStatus::Expired, $round); // only $round
app(ExpireApprovalsAction::class)->execute();                                // int
app(ExpireApprovalsAction::class)->execute(subjectType: Post::class);        // int — posts only

Akcia	execute()	Poznámka
`ApproveAction`	($actor, $approvable, ?DecisionData, ?ApprovalRequest): Approval	Kontrola cez Gate, menovaní schvaľovatelia, delegovanie, váha a stupeň; nahradí držané zamietnutie; opakovanie nič nezmení; vyhodnotí žiadosť.
`RejectAction`	($actor, $approvable, ?DecisionData, ?ApprovalRequest): Approval	Kontrola cez Gate, menovaní schvaľovatelia, delegovanie, váha a stupeň; nahradí držané schválenie; expiráciu nečíta — zamietnutie žiadnu nemá; vyhodnotí žiadosť.
`RequestApprovalAction`	($actor, $approvable, ?DecisionData, ?ApprovalRequest): Approval	Zaznamená čakajúce rozhodnutie s dôvodom a expiráciou (termínom na odpoveď) z DecisionData — alebo vráti živé rozhodnutie aktéra nezmenené; spustí ApprovalRequested. Stav a váhu z DTO ignoruje: vyžiadanie má vždy váhu 1, a to bez chyby — weight() odmietne len fasáda.
`CancelApprovalAction`	($actor, $approvable, ?string $reason, ?ApprovalRequest): ?Approval	Stiahne živé rozhodnutie aktéra alebo to, ktoré urobil ako zástupca, kým delegovanie ešte platí; pri viacstupňovej žiadosti len v otvorenom stupni. $reason nahradí dôvod rozhodnutia, null ho ponechá.
`ToggleApprovalAction`	($actor, $approvable, ?DecisionData, ?ApprovalRequest): bool	Schváli cez ApproveAction s DecisionData a žiadosťou, alebo živé schválenie stiahne s dôvodom z DTO, mäkko ho zmaže a spustí ApprovalCancelled ako CancelApprovalAction. Smer určí živé schválenie, nie stav v DTO.
`OpenApprovalRequestAction`	(ApprovalRequestData $data): ApprovalRequest	Otvorí jednostupňovú žiadosť a uloží jej menovaných schvaľovateľov; required_approvers je predvolene jeden na schvaľovateľa.
`RequestStagedApprovalAction`	($subject, $stages, $rejectOnStageRejection = true, ?$expiresAt, ?$workflow): ApprovalRequest	Otvorí viacstupňové schvaľovanie; každý stupeň uloží svojich menovaných schvaľovateľov.
`OpenWorkflowRequestAction`	($subject, WorkflowPreset, $approvers, ?$expiresAt): ApprovalRequest	Otvorí žiadosť z načítanej šablóny; $expiresAt nahradí expiry šablóny pre toto kolo, null ho ponechá.
`DelegateApprovalsAction`	($delegator, $delegate, ?$startsAt, ?$endsAt): ApprovalDelegation	Overí a uloží delegovanie; spustí ApprovalDelegated.
`RevokeApprovalDelegationAction`	($delegator, ?$delegate): int	Zruší aktívne aj naplánované delegovania; vráti ich počet.
`ExpireApprovalsAction`	(?$now, ?$subjectType): int	Nechá vypršať zmeškané vyžiadania, schválenia a žiadosti — voliteľne len jedného typu subjektu; vráti ich počet.
`CloseApprovalRequestAction`	($subject, ApprovalStatus $outcome = Cancelled, ?ApprovalRequest): int	Uzavrie otvorené kolá subjektu — alebo len zadané — ako zrušené či expirované, bez aktéra a bez kontroly cez Gate; vráti, koľko ich uzavrela.

Pripojenie ku konkrétnej žiadosti

Akcie schválenia, zamietnutia, vyžiadania, stiahnutia a prepnutia prijímajú žiadosť, ku ktorej sa majú pripojiť, ako štvrtý argument — fasáda ju odovzdá cez within(). Bez neho použijú poslednú otvorenú žiadosť schvaľovaného modelu, prípadne zapíšu samostatné rozhodnutie, ak model nikdy žiadnu nemal. Žiadosť iného subjektu vyhodí InvalidApprovalRequestException a uzavretá žiadosť ClosedApprovalRequestException, a to ešte pred zápisom. CloseApprovalRequestAction prijíma žiadosť ako tretí argument a uzavrie len toto kolo:

use RoundlyConsulting\Approvals\Actions\ApproveAction;
use RoundlyConsulting\Approvals\DataTransferObjects\DecisionData;
use RoundlyConsulting\Approvals\Facades\Approvals;

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

// The action's fourth argument is what within($request) passes on the facade.
app(ApproveAction::class)->execute($lead, $release, DecisionData::approved('Ship it'), $request);

DecisionData

DecisionData nesie zámer rozhodnutia. Vytvoríte ho pomenovaným konštruktorom:

Konštruktor	Výsledok
`DecisionData::approved(?$reason, ?$expiresAt, ?$weight)`	Schválenie — weight prebije vypočítanú váhu pre toto jedno rozhodnutie.
`DecisionData::rejected(?$reason, ?$weight)`	Zamietnutie — weight funguje ako pri approved().
`DecisionData::pending(?$expiresAt)`	Čakajúce rozhodnutie. Pre vyžiadanie s dôvodom použite new DecisionData(ApprovalStatus::Pending, $reason, $expiresAt).
`DecisionData::cancelled(?$reason)`	Zrušenie.

RequestApprovalAction zapíše dôvod z DTO ako dôvod vyžiadania a expiráciu ako termín na odpoveď, no stav a váhu ignoruje: vždy zaznamená čakajúce rozhodnutie s váhou 1 a váhu nastavenú v DTO bez chyby zahodí — weight() pred ask() odmietne len fasáda. Váhu nastavte pri rozhodnutí, ktoré na vyžiadanie odpovedá.

Viacstupňová žiadosť s názvom workflow

RequestStagedApprovalAction prijíma expiráciu a názov workflow, ktoré uloží na žiadosť — expiráciu nastavíte aj cez fasádu či trait, názov prijíma len akcia:

use RoundlyConsulting\Approvals\Actions\RequestStagedApprovalAction;
use RoundlyConsulting\Approvals\DataTransferObjects\StageDefinition;
use RoundlyConsulting\Approvals\Enums\ApprovalRule;

app(RequestStagedApprovalAction::class)->execute(
    $release,
    [
        new StageDefinition([$eng1, $eng2], name: 'engineering'),
        new StageDefinition([$product], ApprovalRule::Any, name: 'product'),
    ],
    rejectOnStageRejection: true,
    expiresAt: now()->addDays(3),
);

ApprovalRequestData

ApprovalRequestData je nemenný vstup akcie OpenApprovalRequestAction: subjekt, schvaľovatelia (menovaní schvaľovatelia — ak nikoho nevymenujete, rozhodovať môže ktokoľvek), pravidlo, kvórum, expiresAt a voliteľne requiredApprovers (predvolene jeden na menovaného schvaľovateľa) a názov workflow.

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky