Životný cyklus a stav

Každý prechod je volanie fasády (alebo zodpovedajúcej akcie či metódy modelu), ktoré reklamu uloží a spustí udalosť:

use RoundlyConsulting\Advertisements\Facades\Advertisements;

Advertisements::publish($ad);                     // live now → AdvertisementPublished
Advertisements::publish($ad, now()->addWeek());   // scheduled → AdvertisementPublished
Advertisements::unpublish($ad);                   // back to draft → AdvertisementUnpublished
Advertisements::expire($ad);                      // expired now → AdvertisementExpired
Advertisements::expire($ad, now()->addMonth());   // expires later → AdvertisementExpired
Advertisements::archive($ad);                     // → AdvertisementArchived
Advertisements::delete($ad);                      // soft delete → AdvertisementDeleted

Stav

Každá reklama má status typu RoundlyConsulting\Advertisements\Enums\AdvertisementStatus:

Stav čítajte cez accessor status (alebo pomocné metódy is*() a dopytové scopy). Prepočíta sa pri každom čítaní: reklama, ktorú zverejníte cez publish() alebo archivujete cez archive(), hlási nový stav na tej istej inštancii a reklama, ktorej published_at alebo expires_at uplynie, sa v tej chvíli číta ako Published / Expired — aj v dlho bežiacom workeri a bez opätovného uloženia.

$ad->status;          // AdvertisementStatus::Draft
$ad->publish();
$ad->status;          // AdvertisementStatus::Published — same instance, no refresh needed
$ad->isPublished();   // true

use RoundlyConsulting\Advertisements\Enums\AdvertisementStatus;

$ad->status;                                    // AdvertisementStatus::Published
$ad->status === AdvertisementStatus::Expired;   // true once expires_at passes — no re-save needed
$ad->status->label();                           // "Published"

Stĺpec status

• Stĺpec status obsahuje snímku: create(), update() aj každá akcia životného cyklu zapíšu stav, ktorý v danej chvíli vyplýva z dátumov, a dátumy prebije len Archived.
• Archivácia vydrží update() aj expire() — archivovaná reklama dostane dátum expirácie, no zostane archivovaná. Z archívu ju vyberú len publish() a unpublish().
• Plynutie času stĺpec neprepisuje, takže pri naplánovanej reklame v ňom aj po zverejnení zostane scheduled. Podľa stavu preto filtrujte scopmi (published(), active(), expired(), …), ktoré porovnávajú dátumy, a nie cez where('status', …); stĺpec číta len archived().

Časovanie

• publish($ad, $at) s budúcim okamihom uloží Scheduled; reklama sa zverejní sama, keď published_at nastane — bez jobu či príkazu.
• expire($ad, $at) s budúcim okamihom iba nastaví expires_at; po jeho uplynutí sa reklama číta ako Expired. AdvertisementExpired sa v oboch prípadoch spustí pri volaní — samotné uplynutie času žiadnu udalosť nespúšťa.
• unpublish() vymaže published_at a vráti reklamu do stavu Draft.
• archive() vyradí reklamu zo scopov published, active, scheduled, expired aj draft bez toho, aby ju zmazal.
• delete() je soft delete, ktorý kreatívy ponechá pre obnovenie; forceDelete() odstráni aj ich a expirované reklamy natrvalo odstráni prerezávanie (pozri Artisan príkazy).

Pomocné metódy

Opýtajte sa reklamy na jej stav alebo ju priamo preveďte do iného — metódy modelu sú skratky nad tým istým manažérom, takže spúšťajú tie isté akcie aj udalosti a Advertisements::fake() ich zaznamená:

$ad->isPublished(); $ad->isActive(); $ad->isExpired(); $ad->isScheduled(); $ad->isArchived();

$ad->publish();                   // sugar for Advertisements::publish($ad) — same manager, same event, seen by the fake
$ad->publish(now()->addDay());    // schedule
$ad->expire(now()->addMonth());   // expire later
$ad->unpublish(); $ad->archive(); $ad->delete();
$ad->renderCreative('sidebar');   // sugar for Advertisements::render($ad, 'sidebar')

isActive() platí pre zverejnenú reklamu, ktorej expires_at je prázdny alebo v budúcnosti. Metóda delete() na modeli ide cez manažéra a DeleteAdvertisement, takže soft delete aj AdvertisementDeleted sa spustia bez ohľadu na to, ako ju zavoláte.

Pomocníci enumov

AdvertisementStatus aj AdvertisementEventType používajú spoločný trait Helpers z enums-for-laravel — popisy, možnosti pre výberové polia a validačné pravidlo bez vlastného kódu:

use RoundlyConsulting\Advertisements\Enums\AdvertisementEventType;
use RoundlyConsulting\Advertisements\Enums\AdvertisementStatus;

AdvertisementStatus::toArray();         // ['draft' => 'Draft', 'scheduled' => 'Scheduled', …]
AdvertisementStatus::options();         // {value, label, name} option DTOs for JS selects
AdvertisementStatus::validationRule();  // 'in:draft,scheduled,published,expired,archived'

AdvertisementEventType::Click->counterColumn();   // 'clicks_count'

$request->validate(['status' => ['required', AdvertisementStatus::validationRule()]]);