Varianty obrázkov

Deklarujte zmenšené alebo prevedené odvodeniny obrázkov priamo na skupine — generujú sa automaticky pri pridaní obrázka:

$this->addMediaBucket('photos')
    ->useDisk('public')
    ->storingVariantsOnDisk('cdn')               // variants can live on a different disk
    ->registerVariants(function (VariantRegistrar $v): void {
        $v->add('thumb')->fit('crop')->width(120)->height(120)->format('webp');
        $v->add('display')->width(800)->format('webp')->quality(80)->queued();
        $v->add('hero')->fit('cover')->width(1600)->height(600)->sharpen(2);
    });

Možnosti variantu

• Rozmery — width(), height() a fit() s contain, cover/crop, fill (s výplňou background()) a stretch.
• Formát — format() akceptuje jpg, png, webp, avif, gif (podľa aktívneho driveru).
• Kvalita / vzhľad — quality(1..100), background('#ffffff'), sharpen(int).
• Úložisko — storeOnDisk() pre prepis disku jedného variantu.
• Vykonanie — queued() / nonQueued() per variant.

Čítanie variantov

$media = MediaLibrary::for($user)->first('photos');

$media->getUrl('thumb');             // public URL of the generated variant
$media->getPath('display');          // path on the variants disk
$media->diskFor('thumb');            // the disk the variant was written to
$media->hasGeneratedVariant('thumb');

Každý vygenerovaný variant sa zaznamená v generated_variants s názvom súboru, formátom a diskom, na ktorý sa naozaj zapísal, a každé URL, cesta, stream, presun, kópia aj mazanie vychádza z tohto záznamu:

$media->generated_variants;
// ['thumb' => ['file_name' => 'thumb.webp', 'format' => 'webp', 'disk' => 'hot']]

Variant bez vlastného format() zdedí formát originálu (IMG_0001.JPG → keepformat.jpg; formát, ktorý drivery nevedia zapísať, napríklad .bmp, sa zmení na jpg). Disk variantu sa určí podľa priority — storeOnDisk() variantu, storingVariantsOnDisk() pridania, storingVariantsOnDisk() skupiny, config('media.variants_disk') a nakoniec disk média — a disk, na ktorý variant dopadol, sa zaznamená, takže getUrl(), diskFor() aj mazanie ho nasledujú.

Kontrola a pregenerovanie

MediaLibrary::variants($media) vypíše platné definície, ukáže, čo je vygenerované a čo chýba, a na požiadanie ich vykreslí — bez vynútenia len chýbajúce:

$variants = MediaLibrary::variants($media);

$variants->all();                                   // list<Variant> — every definition that applies
$variants->generated();                             // ['thumb']
$variants->missing();                               // ['display']
$variants->regenerate();                            // render the missing ones → ['display']
$variants->regenerate(only: ['thumb'], force: true); // re-render thumb even though it exists

MediaLibrary::regenerate($media, only: ['thumb'], force: true); // the same verb, flat

Drivery, fronty a eventy

Varianty používajú ext-imagick a prejdú na ext-gd; oba drivery automaticky narovnajú fotky otočené cez EXIF. Predvolene sa generujú synchrónne — frontu zapnete per variant (->queued()), per pridanie (->onQueue('media')) alebo globálne cez config('media.queue_variants_by_default'). Frontovaný GenerateVariantsJob sa odošle až po potvrdení okolitej transakcie (ShouldQueueAfterCommit), takže worker nikdy nehľadá riadok, ktorý ešte neexistuje. VariantHasBeenGenerated sa spustí per variant a VariantsHaveBeenGenerated po dokončení všetkých variantov pridania. getUrl() pozná len varianty, ktoré skupina deklaruje: názov, ktorý skupina nikdy nedefinovala, alebo ešte nevygenerovaný variant vyhodí InvalidVariant, pokiaľ nie je config('media.url_fallback_to_original') nastavené na true — voliteľné názvy si strážte cez hasGeneratedVariant().

Variant, ktorý sa nepodarí vykresliť pri pridaní, naviazaní draftu, attach, presune, kópii či náhrade — obrázok, ktorý driver nevie dekódovať, alebo disk, ktorý odmietne zápis —, sa nahlási vášmu exception handleru a preskočí: ostatné varianty sa vykreslia a volanie uspeje s uloženým médiom. Explicitné regenerate() naopak vyhodí výnimku — namiesto zachytávania výnimky pri pridaní preto kontrolujte MediaLibrary::variants($media)->missing().

Čo sa dekóduje

Oba vstavané drivery súbor pred dekódovaním preveria:

• Len rastrové typy — JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF, HEIC/HEIF a ICO, rozpoznané z bajtov; Imagick každý číta cez explicitný coder daného typu, takže si súbor nikdy nevyberie vlastný dekodér. SVG sa nikdy nedekóduje (SVG môže odkazovať na iné súbory na serveri): SVG médiá nedostanú varianty ani náhľady a regenerate() pre ne nevykreslí nič.
• Limit pixelov — šírka × výška sa prečíta z hlavičky bez dekódovania a obrázok nad media.max_image_pixels (predvolene 50 000 000) sa síce uloží, no bez variantov aj náhľadov; explicitné regenerate() vyhodí InvalidVariant. GD dekóduje v rámci memory_limit PHP (približne 5 bajtov na pixel), preto na GD serveroch s nízkym limitom hodnotu znížte.
• Len prvý snímok — Imagick číta snímok 0 animácie či viacstranového TIFF-u, takže variant animovaného GIF-u je jeho prvý snímok, rovnako ako s GD.