Prepojenia s ďalšími balíkmi
Prepojenie je kód pre iný balík Roundly, aktívny len vtedy, keď je ten balík nainštalovaný. Žiadne nie je závislosťou za behu: každé je uvedené v suggest. Prepojený typ kroku, ktorého balík chýba, ostáva v katalógu s available: false a názvom balíka a publikovanie hlási adapter_missing. Celý balík sa nainštaluje, spustí a vykoná každý vstavaný postup aj bez akéhokoľvek prepojenia.
| Balík | Pridáva |
|---|---|
approvals-for-laravel | Typ kroku approval (+ eskalácie reassign, exclude). Vyžaduje verziu 2.2 alebo novšiu. |
lifecycle-for-laravel | Predvolený TransitionAdapter pre krok transition; kontroly pri publikovaní; voliteľné udalosti prechodov. |
notifications-for-laravel | Typ kroku notify a eskalačná akcia notify, zaradené pod vlastníka inštancie ako kontext schránky. |
opening-hours-for-laravel | Pracovné kalendáre opening_hours:<name>. Vyžaduje verziu 2.1 alebo novšiu. |
forms-for-laravel | Ručné spúšťače s formulárom. |
teams-for-laravel | Kontext vlastníka, strany typu role, kontrola členstva, vlastníctvo subjektu tímom. |
sentinel-for-laravel | Middleware na kontrolu podpisu prichádzajúcej webhook route (len konfigurácia). |
webhooks-for-laravel | Prichádzajúci handler workflows (webhook spúšťače napojené na endpoint) a predvolený doručovateľ kroku webhook. |
Dve prepojenia vyžadujú minimálnu verziu, ktorú vynúti Composer (conflict): approvals-for-laravel ≥ 2.2 (odovzdanie fázy na mieste od 2.1, excluding() od 2.2 — workflows 1.3.0 ju zvýšil z 2.1) a opening-hours-for-laravel ≥ 2.1 (addOpenDays() / addOpenTime()). Staršia nainštalovaná verzia zablokuje composer require / update namiesto zlyhania za behu.
approvals — krok approval
// flat
{ "approvers": [ { "kind": "field", "field": "subject.approver" } ], "rule": "any", "expires_in": { "amount": 2, "unit": "business_days" } }
// staged
{ "stages": [ { "name": "Legal", "approvers": [ { "kind": "role", "role": "legal" } ], "rule": "unanimous" },
{ "name": "CFO", "approvers": [ { "kind": "role", "role": "cfo" } ], "rule": "any" } ],
"expires_in": "P5D", "continue_on_rejection": false }
// an approvals preset (config approvals.workflows), approvers per stage
{ "preset": "payout", "approvers": [ [ { "kind": "field", "field": "subject.approver" } ] ] }
// any of the three, with parties who may never decide (since 1.3.0)
{ "approvers": [ { "kind": "role", "role": "cfo" } ], "rule": "any",
"exclude": [ { "kind": "triggered_by" }, { "kind": "field", "field": "subject.requester" } ] }- Pravidlá: unanimous, quorum (quorum, required), any, weighted — pravidlá balíka approvals. Výsledky: approved, rejected, expired (povinné), cancelled (voliteľný).
- handle() vyhodnotí strany pre každú fázu (nikto → zlyhá s no_approvers; nikdy „rozhodnúť môže ktokoľvek“), vypočíta vypršanie v pracovnom čase a kolo otvorí raz (opakovanie nikdy neotvorí druhé). Výstup: {request_id, rounds, expires_at}. Čaká na rozhodnutie kola plus poistný časovač vo vypršaní + approval.expiry_grace a raz spustí probe hneď po commite.
- Na jednom subjekte môže byť otvorených viac kôl, preto rozhodujte v rámci kola — output.request_id kroku, ktorý sprístupňuje StepRunResource.
- Listener rozhodnutia beží po commite transakcie rozhodujúceho a len signalizuje: rozhodnutie, ktoré sa vráti späť, nič neobnoví.
- Kolo zrušené mimo workflowu pokračuje hranou cancelled, inak zlyhá s approval_cancelled. Zrušenie inštancie zatvorí jej otvorené kolo — či krok čaká, je vo fronte na opakovanie, alebo ešte bežal. Zatvorí sa len čakajúce kolo; rozhodnuté ostane bez zmeny.
- Preradenie (eskalácia), raz na úroveň eskalácie: kolo s fázami, ktorého otvorená fáza má názov, sa odovzdá na mieste — schvaľovatelia, ktorí už rozhodli, ostanú uvedení a ich rozhodnutia platia, nerozhodnutí sa nahradia, kolo si ponechá absolútny čas vypršania a output.request_id sa nezmení. Kolo bez fáz alebo nepomenovaná fáza sa nahradí novým kolom pre nové strany s pôvodným vypršaním; rozhodnutia v starom kole sa neprenášajú. Ak chcete odovzdanie na mieste, fázy pomenujte.
- Ručné opakovanie zlyhaného kroku approval si ponechá rovnaký idempotentný kľúč, takže znova načíta kolo, ktoré už otvoril. Chyby schvaľovania zlyhajú natrvalo (invalid_approval_request, unknown_approval_preset).
// Decide within the round the step opened — its output.request_id (exposed by StepRunResource)
Approvals::as($user)->for($subject)->within($round)->approve();Vylúčení rozhodovatelia (exclude, od 1.3.0) — zoznam strán (user, field, role, triggered_by) s aktérmi, ktorí o kole nikdy nesmú rozhodnúť, napríklad žiadateľ schvaľujúci vlastnú žiadosť. Funguje s jednoduchými, fázovanými aj prednastavenými kolami:
- Strany sa vyhodnotia pri otvorení kola (bez filtra členstva vo vlastníkovi) a odovzdajú sa do excluding() v approvals: approvals ich uloží ku kolu, odmietne ich rozhodnutie (UnauthorizedApprovalException), nikdy ich nevyzve, nedovolí im konať ako zástupca a nedovolí žiadnemu zástupcovi rozhodnúť za nich.
- Zároveň sa pred otvorením kola odstránia z každého zoznamu schvaľovateľov. Zoznam, ktorý ostane prázdny, zlyhá s no_approvers — nikdy „rozhodnúť môže ktokoľvek“. Kvóra a required sa obmedzia na zostávajúcich schvaľovateľov.
- Reassign to rešpektuje: cieľové strany prídu o vylúčených aktérov, či sa fáza nahradí na mieste, alebo sa otvorí nové kolo.
- Publikovanie overí exclude ako každý zoznam strán a odmietne zoznam schvaľovateľov (jednoduchý, fázu aj fázu predvoľby), ktorého každá strana je aj v exclude — approvers_excluded na ceste tohto zoznamu. Prekryv, ktorý sa prejaví až za behu (rola, ktorej jediným členom je ten, kto workflow spustil), zlyhá s no_approvers.
- Approvals zapisuje zoznam do ochranných stĺpcov svojej migrácie 0008_add_decision_guards_to_approvals_tables; kolá bez exclude sa ich nikdy nedotknú, preto túto migráciu spustite pred publikovaním kroku s exclude.
lifecycle — krok transition a udalosti prechodov
- Lifecycles::for($subject, $lifecycle)->by($user)|asSystem()->because($reason)->idempotencyKey($key)->attempt($transition). Vykonaný → transitioned. Zamietnutý → hrana denied, inak zlyhá s transition_denied:<code>.
- IdempotencyConflictException → idempotency_conflict; prehratý súbeh → opakuje sa; nesprávne použitie (neznámy lifecycle, zmazaný alebo neuložený subjekt) → transition_unusable.
- Publikovanie overí, že prechod existuje (unknown_transition), a odmietne set_field na stavovom stĺpci lifecycle (field_not_writable). Dôvodom v histórii lifecycle je workflow {key} v{n} #{instance ulid} (alebo reason uzla).
- Voliteľne: so zapnutým workflows.bridges.lifecycle.emit_transitions vyšle každá zmena stavu lifecycle po commite svojej transakcie lifecycle.<lifecycle>.<transition> pre subjekt — workflow tak môže začať (alebo wait pokračovať), keď záznam dosiahne stav, bez ohľadu na to, kto ho posunul. Vypršanie alebo prevzatie použije svoj druh (lifecycle.purchase.expired). Payload je {lifecycle, transition, kind, from, to, history_id}, aktérom je používateľ, ktorý prechod spustil, a idempotentným kľúčom je id záznamu v histórii lifecycle.
# every lifecycle state change emits lifecycle.<lifecycle>.<transition>
WORKFLOWS_LIFECYCLE_EMIT_TRANSITIONS=onnotifications — krok notify a eskalačná akcia
{ "notification": "purchase.approved", "recipients": [ { "kind": "field", "field": "subject.requester" } ],
"data": { "amount": { "ref": "subject.amount" } }, "actor": "triggered_by" }Notifications::send($type, $subject, $recipients, $data, $actor, $context, $idempotencyKey). Výstup {recipients: n}; bez príjemcov sa krok dokončí s 0. Publikovanie overí typ (unknown_notification_type) a príjemcov. Odmietnutie zo strany notifications zlyhá natrvalo ako notification_refused:<kód z notifications> — nikdy sa neopakuje.
Kontext schránky (od 1.3.0): krok aj eskalačná akcia notify zaraďujú položky schránky pod kontext, ktorý určuje workflows.bridges.notifications.context (WORKFLOWS_NOTIFICATIONS_CONTEXT):
| Hodnota | Kontext |
|---|---|
| owner | Predvolené; aj prázdne alebo kľúč chýbajúci v staršom publikovanom configu. Vlastník inštancie (Context::of($owner): kľúč <alias>:<id>, popis z notificationContextLabel(), inak name); pri inštancii bez vlastníka žiadny. |
| off, none, null, false | Žiadny — správanie z 1.2. |
| class-string ResolvesNotificationContext | notificationContext($instance, $owner, $subject) vráti Notifications\Context, model, reťazec s kľúčom kontextu alebo null; čokoľvek iné vyhodí InvalidWorkflowsConfigurationException (krok zlyhá s exception). |
Vlastník, ktorého kľúč stĺpce kontextu v notifications neudržia (notifications.context_key_type, inak notifications.key_type — napríklad tímy s ULID a kontexty s bigint), sa odošle bez kontextu namiesto zlyhania odoslania. Ak ho chcete zaradiť, nastavte typ kľúča kontextu v notifications na typ kľúča vlastníka.
opening-hours — kalendáre
opening_hours:<name> číta rozvrh otváracích hodín <name> vlastníka (otvorené intervaly, sviatky, výnimky) a pracovný čas počíta priamo opening-hours: „2 pracovné dni“ a „4 pracovné hodiny“ sa počítajú presne tak ako v opening-hours, s obmedzením opening-hours.search_days. Model vlastníka musí implementovať OpeningHoursOwner (use HasOpeningHours) — workflows:doctor zlyhá pri aktívnej definícii, ktorej model vlastníka ho nemá. Pri teams je vlastníkom tím, preto model tímu nahraďte takým, ktorý ho pridá:
// config/teams.php: 'models' => ['team' => App\Models\Team::class]
namespace App\Models;
use RoundlyConsulting\OpeningHours\Concerns\HasOpeningHours;
use RoundlyConsulting\OpeningHours\Contracts\OpeningHoursOwner;
use RoundlyConsulting\Teams\Models\Team as BaseTeam;
class Team extends BaseTeam implements OpeningHoursOwner
{
use HasOpeningHours;
}forms, teams a sentinel
- forms — {"trigger": "manual", "form": "purchase-form"} overí vstup cez forms-for-laravel; ->withForm($request, submit: true) uloží odoslanie a jeho uuid vloží do payloadu spúšťača. Neznámy formulár → unknown_form; spúšťač s formulárom bez nainštalovaného forms → adapter_missing.
- teams — kroky inštancie, ktorú vlastní tím, bežia v Teams::runAs($team) bez ohľadu na kontext, z ktorého boli odoslané; rovnako kontroly podmienok, eskalácie aj prehľadávanie subjektov plánu for_each a jeho where. {"kind": "role", "role": "legal"} sa vyhodnotí na aktívnych členov tímu s touto rolou; strany user, field a triggered_by musia byť aktívni členovia; subjekty BelongsToTeam / ScopedToTeam vlastní ich tím.
- sentinel — bez kódu: nastavte workflows.webhooks.verify_middleware = ['sentinel.signed:<profile>'] a prichádzajúca webhook route bude overovať podpisy RFC 9421.
webhooks — prichádzajúce endpointy a krok webhook
Webhooks for Laravel zabezpečuje podpisy, ochranu pred opakovaním, opakovania doručení, obmedzovanie, ochranu pred SSRF, podpisovanie a záznam doručení; prepojenie ho napojí na workflowy oboma smermi. Prichádzajúce: prepojenie zaregistruje alias handlera workflows a prichádzajúci endpoint nasmerovaný naň spustí aktívny workflow vlastníka endpointu, ktorého webhook spúšťač tento endpoint uvádza, s id doručenia ako kľúčom, takže replay workflow nikdy znova nespustí — úplné pravidlá nájdete v časti Spúšťače. Odchádzajúce: krok webhook odosiela cez odosielanie vo webhooks:
{ "type": "webhook", "config": {
"endpoint": 12,
"event": "invoice.approved",
"payload": { "invoice": { "ref": "subject.number" }, "amount": { "ref": "subject.amount" } }
} }
// in PHP: ->webhook('send', $endpoint->id, 'invoice.approved', ['invoice' => Ref::subject('number')])- Zaregistruje sa, keď je k dispozícii implementácia DeliversWebhooks: väzba v kontajneri, workflows.adapters.webhooks, inak toto prepojenie. Adaptér aplikácie prevezme celý krok a kontroly udalostí z webhooks uvedené nižšie potom neplatia.
- Endpoint je id odchádzajúceho endpointu, ktorý sa cez webhooks hľadá v rozsahu vlastníka inštancie (Webhooks::for($owner)->outbound()->find()); bez vlastníka sa nájdu len endpointy bez vlastníka. Vlastníci sa musia presne zhodovať. Endpoint iného vlastníka, chýbajúci endpoint aj id, ktoré nemôže byť kľúčom typu primary_key_type vo webhooks, ukončia krok s endpoint_not_found, pri chybnom id bez akéhokoľvek dopytu. endpoint je špecifický pre vlastníka: pri importe šablóny sa vymaže a označí.
- Payload je mapa hodnôt alebo odkazov vyhodnotených za behu, rovnako ako start_workflow.input.
- Práve raz: odoslanie beží v $context->once('delivery') a Webhooks::send() dostane idempotentný kľúč kroku ako svoje id, takže opakovanie návštevy nič nové nezaradí, ani keď sa záznam once() stratil. webhooks odošle job doručenia až po commite transakcie.
- Výsledok queued, výstup {delivery: "msg_…"} — id doručenia tak, ako ho ukazuje záznam doručení vo webhooks. Krok sa dokončí, keď je doručenie zaradené; či dorazí, je úlohou webhooks (opakovania, DeliveryFailed).
- Kontroly pri publikovaní cez prepojenie: udalosť musí zodpovedať pravidlu typu udalosti vo webhooks (^[a-z0-9_]+(\.[a-z0-9_]+)*$, najviac 100 znakov), inak invalid_config na /event; ak je nastavený zoznam povolených outbound.event_types, udalosť v ňom musí byť, inak unknown_webhook_event.
| webhooks vyhodí | Krok zlyhá s | Pomôže ručné opakovanie |
|---|---|---|
EndpointNotFoundException | endpoint_not_found | nie — chýba, patrí inému vlastníkovi alebo má chybné id |
EndpointNotAcceptingException | endpoint_not_accepting:disabled / :not_subscribed | áno, po zapnutí alebo prihlásení endpointu |
InvalidEventTypeException | invalid_event_type | nie — napr. zoznam povolených sa po publikovaní zmenil |
PayloadTooLargeException | payload_too_large | nie — nad outbound.max_payload_bytes |
Žiadne z nich sa automaticky neopakuje; čokoľvek iné, čo webhooks vyhodí, je opakovateľná exception. Ak chcete doručovať cez vlastnú službu, implementujte Contracts\DeliversWebhooks (deliver(?Model $owner, string $endpoint, string $event, array $payload, string $idempotencyKey): int|string) — idempotentne voči kľúču — a uveďte ju vo workflows.adapters.webhooks.
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 kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
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.