NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky
Credits for Laravel

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 it

Nadradený 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áciaOveruje sa vočiZapisuje sa na
hold($amount)dostupný zostatok každej úrovnekaždá úroveň: vrátená rezervácia a prepojená rezervácia na každom nadradenom
modify(-$amount) / deduct()dostupný zostatok každej úrovnekaždá úroveň: po jednom zázname v knihe pohybov
setTo() pri znížení zostatkukaždá úroveň, pre rozdielkaž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íklen 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 company

Rezervá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 included

Je 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 balances

Vypnutie 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 kryptomien

Odoslaní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.