Vnorené rozpočty
Od verzie 2.2.0, voliteľné. Vlastník môže byť súčasťou iného: osoba v tíme, tím vo firme. Jeho míňanie sa potom započíta aj do zostatku každého nadradeného vlastníka v tej istej skupine a ten ho zároveň obmedzuje. Jedno volanie overí a zapíše celú reťaz v jednej transakcii — už nemusíte rezervovať každú úroveň zvlášť, ručne vracať skoršie rezervácie, keď neskoršia zlyhá, ani riskovať, že dvaja súrodenci prejdú vlastnou kontrolou a spolu prečerpajú spoločného nadradeného.
Nastavenie
Nadradení sú vypnutí, kým ich nezapnete. Kým je credits.parents.enabled vypnuté, žiadny nadradený sa nevyhľadáva a každý vlastník stojí sám, presne ako pred verziou 2.2.0:
CREDITS_PARENTS=true
CREDITS_PARENTS_MAX_DEPTH=8 # optional: how many ancestors a chain may have (default 8, 1–64)Pri zapnutých rezerváciách publikujte a spustite aj migráciu link_credit_holds_to_their_origin (pozrite Inštalácia). Nadradení bez rezervácií migráciu nepotrebujú.
Určenie nadradeného
Implementujte na vlastníkovi HasCreditParent:
use RoundlyConsulting\Credits\Interfaces\Creditable;
use RoundlyConsulting\Credits\Interfaces\HasCreditParent;
use RoundlyConsulting\Credits\Traits\HasCredits;
final class Member extends Model implements Creditable, HasCreditParent
{
use HasCredits;
public function creditParent(): ?Team
{
return $this->team; // null at the top
}
}Alebo zaregistrujte jeden resolver pre všetkých vlastníkov, napríklad pre modely, ktoré nemôžete meniť. Má prednosť pred creditParent() každého vlastníka, preto ostatných vráťte ich vlastnej metóde:
Credits::resolveParentsUsing(fn ($owner) => $owner instanceof User
? $owner->currentTeam
: ($owner instanceof HasCreditParent ? $owner->creditParent() : null));
Credits::resolveParentsUsing(null); // remove itNadradený musí byť tiež Model&Creditable a jeho kniha pohybov musí byť na tom istom spojení ako kniha podriadeného, lebo celú reťaz pokrýva jedna transakcia.
Čo robí ktorá operácia na reťazi
available je zostatok skupiny mínus jej aktívne rezervácie, ako všade v balíku. Každá úroveň sa stráži voči credits.minimum_balance, pokiaľ volanie nepovoľuje prečerpanie:
| Operácia | Overuje sa voči | Zapisuje sa na |
|---|---|---|
hold($amount) | dostupný zostatok každej úrovne | každá úroveň: vrátená rezervácia a prepojená rezervácia na každom nadradenom |
modify(-$amount) / deduct() | dostupný zostatok každej úrovne | každá úroveň: po jednom zázname v knihe pohybov |
setTo() pri znížení zostatku | každá úroveň, pre rozdiel | každá úroveň, rozdiel |
modify(+$amount) / add() / setTo() pri zvýšení zostatku | — | len vlastník |
capture($hold, $amount) | — (rezervácia to už vyhradila) | každá úroveň: každá rezervácia strhnutá, po jednom odpise |
capture(…, allowOverdraft: true) nad rámec rezervácie | — | každá úroveň, celá suma |
release($hold) | — | rezervácia každej úrovne uvoľnená |
expireHolds() | — | úrovne rezervácie expirujú naraz, v jednej transakcii |
reset() | len vlastník | len vlastník — obnovenie sa nadradených nikdy nedotkne |
setTo() sa overí a zapíše na každej úrovni, len keď zostatok znižuje; zvýšenie sa týka iba vlastníka. Podriadený, ktorého vlastný rozpočet je vyšší než rozpočet nadradeného, je aj tak obmedzený nadradeným:
// company 100, team 1 000, person 1 000
Credits::availableWithin($person)->available; // 100
Credits::for($person)->hold(101); // InsufficientCreditsException, naming the companyRezervácie: jedna na úroveň
Rezervácia vlastníka s nadradenými je jeden riadok rezervácie na každú úroveň. Rezervácia, ktorú volanie vráti, je pôvodná (chain_depth 0). Každý nadradený dostane prepojenú rezerváciu (chain_depth 1, 2, …), ktorej origin_hold_id ukazuje späť na pôvodnú, s rovnakou sumou, skupinou, expiráciou, popisom aj meta. held() a available() každej úrovne započítajú jej vlastnú rezerváciu, takže zostatok nadradeného odráža rezervácie všetkých podriadených bez ďalšieho dopytu. Strhnutie, uvoľnenie aj expirácia načítajú úrovne rezervácie spolu s ich vlastníkmi (eager loading), takže fungujú aj pri Model::preventLazyLoading() (od 2.2.1).
Rezerváciu riešte cez pôvodnú: capture() a release() na prepojenej úrovni vyhodia LinkedCreditHoldException. Rozlíšite ich cez $hold->isLinked() a $hold->originKey(). Úroveň, ktorá bola medzitým vyriešená samostatne, sa preskočí.
Zamykanie
Každý zápis do reťaze zamyká vlastníkov zhora nadol: najprv koreň, potom každú úroveň až po vlastníka. Dva zápisy na súrodencov sa preto zoradia na spoločnom nadradenom a druhý rozhoduje podľa zostatku, ktorý zanechal prvý — z dvoch súrodencov, ktorí súperia o posledné kredity nadradeného, ich dostane presne jeden, na každej úrovni izolácie. Požiadavky v opačnom poradí nemôžu uviaznuť, lebo žiadny zápis nezamkne podriadeného pred nadradeným. Ide o ten istý mechanizmus credit_locks ako pri jednom vlastníkovi (pozrite Ochrana pred prečerpaním), overený na Postgrese testami súbehu dvoch relácií.
Čítanie — availableWithin()
$within = Credits::availableWithin($person, 'ai'); // or Credits::for($person)->bucket('ai')->availableWithin()
$within->available; // the smallest available balance along the chain
$within->limitedBy; // the owner that has it (the nearest one on a tie)
$within->limitedByParent($person); // true when an ancestor sets the limit
$within->levels; // owners in the chain, the person includedJe to čítanie, nie prísľub: ak sumu chcete mať istú, rezervujte ju. Bez nadradených, alebo keď sú vypnutí, ide o vlastné available() vlastníka.
Keď niektorá úroveň odmietne
InsufficientCreditsException pomenuje vlastníka, ktorý odpis zablokoval:
use RoundlyConsulting\Credits\Exceptions\InsufficientCreditsException;
try {
Credits::for($person)->hold(500);
} catch (InsufficientCreditsException $e) {
$e->creditable; // the blocking owner (a parent, or the person itself)
$e->requestedBy; // the person the call was made on
$e->blockedByParent(); // true when a parent blocked
$e->ownerType(); // the blocking owner's morph type
$e->ownerKey(); // its key
$e->available; // what that owner had available
$e->requested; // -500
}Úrovne sa overujú od vlastníka smerom nahor, takže sa pomenuje najbližší blokujúci vlastník. Odmietnutie nadradeným znie „Insufficient credits in the budget of [App\Models\Team#7]: tried to deduct 500 but only 120 are available there.“ (credits::messages.insufficient_within_parent, v angličtine aj slovenčine); odmietnutie samotným vlastníkom ponechá doterajšie správy. InvalidCreditParentException nastane, keď sa reťaz nedá prejsť — cyklus, viac nadradených než credits.parents.max_depth, alebo nadradený, ktorého kniha pohybov je na inom spojení — a nič sa nezapíše.
Udalosti
Každá sa spustí raz pre každú zmenenú úroveň, s vlastníkom tejto úrovne, takže aplikácia môže posielať upozornenia „rozpočet sa míňa“ či „rozpočet vyčerpaný“ pre každú úroveň zvlášť:
- CreditsHeld($creditable, $hold, $available), kde $available je dostupný zostatok tejto úrovne po rezervácii.
- CreditsModified($creditable, $credit, $balance) pre odpis každej úrovne vrátane strhnutia.
- CreditHoldCaptured($creditable, $hold, $credit, $released).
- CreditHoldReleased($hold) a CreditHoldExpired($hold).
Testovanie s fake
Credits::fake() prechádza nadradených rovnako ako kniha pohybov: odpis či rezervácia podriadeného sa overí a zaznamená na každej úrovni, takže môžete overovať jednotlivé úrovne:
$fake = Credits::fake();
Credits::for($person)->hold(40);
$fake->assertHeld($company, 40);
$fake->assertHeld($person, 40);
Credits::availableWithin($person)->limitedBy; // read from the fake's balancesVypnutie nadradených
Vypnite ich, až keď už nie je aktívna žiadna rezervácia vytvorená na vlastníkovi s nadradenými: prepojené úrovne rezervácie sa riešia, len kým sú nadradení zapnutí.
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.