Umiestnenia

Umiestnenie je zóna, v ktorej sa reklamy vykresľujú — bočný panel, hlavička, feed. Má preložiteľný názov, slug ako kľúč pre kód a voliteľnú šírku a výšku v pixeloch, podľa ktorých sa prispôsobí variant display kreatívy aj záložná textová reklama:

use RoundlyConsulting\Advertisements\Models\Placement;

$sidebar = Placement::query()->create([
    'name' => ['en' => 'Sidebar', 'sk' => 'Bočný panel'],
    'slug' => 'sidebar',   // optional — generated from the fallback-locale name when empty
    'width' => 300,        // optional pixel size for the display variant and the text ad
    'height' => 250,
]);

$leaderboard = Placement::query()->create(['name' => ['en' => 'Leaderboard'], 'width' => 728, 'height' => 90]);
$leaderboard->slug;        // "leaderboard"

Ak slug nevyplníte, vygeneruje sa z názvu v záložnom jazyku (Side Banner → side-banner, pri obsadení so sufixom -2). Zadaný slug sa zachová bajt po bajte, obsadený vyhodí SlugAlreadyTakenException a potom sa už nikdy nezmení — je totiž kľúčom úložiska kreatív umiestnenia (creative:{slug}), takže premenovanie ich nesmie osirotiť.

Priraďovanie a servírovanie

use RoundlyConsulting\Advertisements\Facades\Advertisements;
use RoundlyConsulting\Advertisements\Models\Advertisement;

Advertisements::for($ad)->placements()->attach(['sidebar', $leaderboard->id]); // models, ids, or slugs
Advertisements::for($ad)->placements()->sync(['sidebar']);
Advertisements::for($ad)->placements()->detach(['sidebar']);
Advertisements::for($ad)->runsIn('sidebar'); // true

// Active ads in a placement, or one at random:
Advertisements::in('sidebar')->get();
Advertisements::random('sidebar');

Advertisement::query()->forPlacement($sidebar)->get(); // model, id, or slug

• for($ad)->placements() — attach() pridá umiestnenia bez odpojenia existujúcich, sync() nahradí celú množinu, detach() ich odoberie. Každá vráti reklamu s nanovo načítanými umiestneniami.
• Každá metóda prijíma modely umiestnení, id alebo slugy. Reťazec sa najprv porovná so slugom; reťazec zo samých číslic, ktorý žiadne umiestnenie nepoužíva ako slug, sa potom berie ako id, takže vstup z formulára či routy („12“) funguje bez úprav. Neznámy odkaz attach(), sync() a detach() preskočia a v in() ani forPlacement() nevyberie nič.
• for($ad)->runsIn($placement) povie, či je reklama priradená.
• in($placement) je active()->forPlacement($placement); random() vyberie jednu náhodnú aktívnu reklamu, voliteľne pre umiestnenie, alebo vráti null.
• targetedIn($placement, $viewer) je verzia in() s ohľadom na polohu — pozri Geografické cielenie.

Relácie

$ad->placements;            // BelongsToMany<Placement> — the pivot carries meta + timestamps
$sidebar->advertisements;   // BelongsToMany<Advertisement>
$sidebar->width;            // ?int
$sidebar->height;           // ?int

Pivot advertisement_placement je pre každú dvojicu unikátny; jeho cudzie kľúče sa kaskádovo zmažú, keď sa riadok reklamy alebo umiestnenia natrvalo odstráni. Umiestnenia používajú soft delete.