Potvrdzovanie zmien

Model zmenený mimo aplikácie zostáva zamietnutý, kým zmenu niekto s dôvodom neprijme. Prijatie je potvrdenie: prepečatenie, ktoré zaznamená kto, prečo, čo sa zmenilo a aký bol stav — v denníku chránenom MAC.

$result = Sentinel::for($invoice)->by($admin)->because('INC-88: refund fixed by the DBA')->acknowledge();

$result->acknowledged;   // false when the model was intact (nothing written)
$result->before;         // the VerificationResult it replaced

$invoice->acknowledgeTampering('INC-88: refund fixed by the DBA', $admin);

AcknowledgementResult má acknowledged (false, ak bol model neporušený — nič sa nezapíše), before (VerificationResult, ktorý nahradil) a seal (nový SealResult).

Pravidlá

• Dôvod je vždy povinný, orezaný, 1–sealing.reason_max_length znakov (AcknowledgementDeniedException::reason / reasonTooLong).
• Mimo konzoly je povinný aktér (actorRequired). Bez by() sa použije prihlásený používateľ; v konzole bez neho sa ako aktér zaznamená systém.
• Rozhoduje politika: predvolene Gate ability z acknowledgement.ability (ak je nastavená), volaná s modelom a názvom pečate. Ak ju chcete nahradiť — napríklad schválením dvoma osobami — naviažte Contracts\AcknowledgementPolicy.
• Overenie pri načítaní je počas volania pozastavené, takže zmenený model sa dá načítať.
• Nový záznam v denníku (udalosť acknowledged) nesie predošlý stav, názvy zmenených atribútov, aktéra a dôvod; TamperAcknowledged sa spustí po commite. Dodatočná úprava uloženého dôvodu či aktéra poruší MAC záznamu (EntryInvalid).

use Illuminate\Support\Facades\Gate;

Gate::define('acknowledge-tampering', fn (User $user, Model $model, string $seal): bool => $user->isAdmin());
// SENTINEL_ACKNOWLEDGE_ABILITY=acknowledge-tampering

Ploché tvary

Sentinel::acknowledge($invoice, 'INC-88: refund fixed by the DBA', $admin, 'financial');   // AcknowledgementResult
Sentinel::unseal($invoice, 'GDPR erasure #12', $admin, 'identity');    // bool: a seal row existed
Sentinel::ledgerHistory($invoice, 'financial', limit: 20);             // list<LedgerRecord>, newest first (1–1000)
Sentinel::currentSeal($invoice);                                       // ?SealRecord — the default seal, unverified

Odpečatenie

unseal($reason) zmaže riadok pečate a pridá tombstone unsealed (raz — opakované odpečatenie nič nezapíše) s dôvodom, aktérom a stavom, ktorý pečať mala; SealRemoved sa spustí po commite. Odstránenie pečate je rovnako silné ako prijatie zmeny, preto prebehnú tie isté kontroly dôvodu, aktéra a politiky. Potom sa pečať overí ako Unsealed (benevolentná) alebo Missing(unsealed) (striktná); striktná pečať sa vráti cez acknowledge(), nikdy cez seal().

use RoundlyConsulting\Sentinel\Actions\Seals\UnsealModelAction;
use RoundlyConsulting\Sentinel\DataTransferObjects\UnsealRequest;

Sentinel::for($invoice, 'identity')->by($admin)->unseal('GDPR erasure #12');
Sentinel::unseal($invoice, 'GDPR erasure #12', $admin, 'identity');
app(UnsealModelAction::class)->execute(new UnsealRequest($invoice, 'identity', 'GDPR erasure #12', $admin));

Načítanie zmeneného modelu

Pečať, ktorá overuje pri načítaní s Reaction::Throw, zmenený riadok nenačíta — ani v route-model bindingu, teda skôr, než sa spustí kontrolér na potvrdenie. Pre obrazovku potvrdenia ho načítajte cez find() / findOrFail(), ktoré pre ten jeden dopyt pozastavia overenie pri načítaní (globálne scopes ostanú; findOrFail() je v route 404):

Route::bind('tamperedInvoice', fn (string $id) => Sentinel::model(Invoice::class)->findOrFail($id));
Route::post('/admin/invoices/{tamperedInvoice}/acknowledge', AcknowledgeInvoice::class);

$invoice = Sentinel::withoutVerification(fn () => Invoice::query()->find($id));   // any query, verify-on-retrieve off

Inde zostáva overovanie zapnuté; samotné acknowledge() ho pozastaví len v rámci vlastného volania. Obe fungujú aj s fake.