Pravidelné obnovenie

Pravidelné obnovenie nastaví zvolené skupiny na presný zostatok raz za obdobie — mesačné bezplatné kredity, denný limit. Je idempotentné pre vlastníka, skupinu a obdobie, takže dvojito naplánovaný beh, dva servery ani zopakovaný job neobnovia skupinu dvakrát. Obnovenie potrebuje tabuľku credit_resets (pozrite Inštalácia) a žiadny prepínač:

use RoundlyConsulting\Credits\Enums\ResetPeriod;
use RoundlyConsulting\Credits\Facades\Credits;

$result = Credits::for($user)->bucket('free')->reset(ResetPeriod::Monthly, to: 100);

$result->reset;    // true — false when this bucket was already reset this period
$result->period;   // '2026-11'
$result->credit;   // the delta row, or null (already reset, or the balance already matched)

Credits::reset($user, 'billing-cycle-7', to: 500, bucket: 'pro');     // an explicit period key
$user->resetCredits(ResetPeriod::Daily, to: 10, bucket: 'daily_allowance');

• Idempotentné pre obdobie: jeden riadok credit_resets na vlastníka, skupinu a kľúč obdobia, zapísaný v transakcii obnovenia pod zámkom vlastníka. Druhé obnovenie v tom istom období nič nezapíše a vráti reset: false.
• Kľúče obdobia sa určia z aktuálneho času v časovom pásme aplikácie: Daily → 2026-11-09, Weekly → 2026-W46 (rok podľa ISO týždňov), Monthly → 2026-11, Yearly → 2026. Alebo zadajte vlastný kľúč (1–64 znakov, orezaný) pre fakturačné cykly, ktoré sa neriadia kalendárom.
• Obnovenie je setTo($to): jeden rozdielový záznam (meta ['reset_period' => key], pokiaľ nezadáte vlastné meta), CreditsModified a tá istá ochrana — zníženie skupiny pod jej rezervované kredity sa odmietne, pokiaľ nie je povolené prečerpanie. Odmietnuté obnovenie nezanechá žiadnu značku, takže ho ďalší beh zopakuje.
• K dispozícii je aj Credits::reset($owner, $period, to:, bucket:, description:, meta:, allowOverdraft:) a $user->resetCredits($period, to:, …, bucket:).

Plánovanie — credits:reset

credits:reset {bucket*}
    {--period=monthly : daily, weekly, monthly or yearly}
    {--key= : an explicit period key instead of --period}
    {--to=0 : the balance to reset to}
    {--timezone= : the timezone the period is read in (default app.timezone)}
    {--description= : description for the delta rows}
    {--allow-overdraft : reset even when held credits would breach the minimum}
    {--resolvers : reset the owners the credits.modifiable resolvers yield}

Predvolene obnoví každého vlastníka, ktorý má v danej skupine záznamy — vlastníci sa načítajú cez svoj morph typ a záznam, ktorého vlastník už neexistuje, sa nahlási a preskočí. S --resolvers obnoví namiesto toho vlastníkov, ktorých vrátia closures z credits.modifiable; to potrebujete pre vlastníkov, ktorí kredity ešte nikdy nemali. Kľúč obdobia sa určí raz za beh, takže beh, ktorý prekročí polnoc, obnoví všetkých do toho istého obdobia:

// routes/console.php — free credits back to 100 on the 1st, in the business's timezone
Schedule::command('credits:reset free --period=monthly --to=100 --timezone=Europe/Bratislava')
    ->monthlyOn(1, '00:05')
    ->timezone('Europe/Bratislava');

// daily allowance, topping up every user (resolvers in credits.modifiable)
Schedule::command('credits:reset daily_allowance --period=daily --to=10 --resolvers')->dailyAt('00:01');

Druhé spustenie toho istého príkazu v jednom období už nič neobnoví. Príkaz vypíše, koľko vlastníkov obnovil a koľko už v danom období obnovených bolo; vlastník, ktorého ochrana odmietne, sa nahlási, beh pokračuje a príkaz skončí s kódom 1. Chybné voľby — --period=hourly, neceločíselné --to, priveľký --key, neznáme --timezone — zlyhajú skôr, než sa čokoľvek zapíše.

Tabuľka credit_resets

Primárny kľúč (creditable_type, creditable_id, bucket, period) — záruka idempotencie. Na zostatok sa nikdy nečíta.