Prílohy

Správy nesú plnohodnotné prílohy postavené na media-library-for-laravel. Každá správa má súkromnú skupinu attachments: obrázky dostanú rebrík responzívnych šírok, ostatné súbory (PDF, zip, …) sa uložia ako nezmenený originál. Prílohy sú predvolene súkromné a dostupné len cez podpísané krátkodobé streamovacie URL z media-library — bez ohľadu na to, či je vlákno verejné.

Aby podpísaná URL zostala jedinou cestou k súboru, súkromné prílohy (aj ich varianty) sa ukladajú na messages.media.private_disk — predvolene neverejný disk local z Laravelu — a nikdy na predvolený disk public z media-library, ktorý php artisan storage:link sprístupní pod /storage.

Príprava

media-library je pevná závislosť a nainštaluje sa spolu s balíkom messages, takže nič nezapínate — publikujte jej migráciu (ako v Inštalácii) a voliteľne aj konfiguráciu:

php artisan vendor:publish --tag="media-migrations"   # the `media` table attachments live in
php artisan vendor:publish --tag="media-config"       # optional: default disk, streaming route
php artisan migrate                                   # creates the `media` table

Odoslanie s prílohami

Builder správy prijme vopred nahrané tokeny draft médií aj čerstvo nahraté súbory. Draft vznikne v kroku nahrávania cez media-library, ešte pred existenciou správy:

use RoundlyConsulting\MediaLibrary\Facades\MediaLibrary;

// Upload step — before the message exists. Hand the token back to the client.
$draft = MediaLibrary::draft($request->file('photo'))->toBucket('attachments');
$token = $draft->draft_token;

use RoundlyConsulting\Messages\Facades\Messages;

$message = Messages::to($thread)->from($alice)
    ->withAttachment($draftToken)                 // a media-library draft token
    ->withAttachments([$tokenA, $tokenB])         // several at once
    ->attach($request->file('photo'))             // an UploadedFile
    ->send('Here are the files');

Oba druhy sa naviažu na správu vnútri SendMessage — v transakcii, pred spustením MessageSent — takže listenery, broadcasty aj príjemcovia vidia prílohy okamžite. Neplatný alebo expirovaný token draftu zruší celé odoslanie a nezostane po ňom osirotená správa. Rovnaké vstupy má aj SendMessageData ako attachments (tokeny) a uploads (súbory).

K uloženej správe môžete prílohu pridať aj priamo cez fluentný adder z media-library:

$message->addMedia($uploadedFile)->toMediaBucket('attachments');

Čítanie príloh

$message->attachments();        // Collection<Media> — every attachment, in bucket order
$message->imageAttachments();   // images only
$message->fileAttachments();    // non-image (passthrough) files
$message->hasAttachments();     // bool
$message->attachmentsBucket();  // 'attachments' — from messages.media.attachments_bucket

Súkromné podpísané URL

$media = $message->imageAttachments()->first();

$message->attachmentUrl($media);                  // signed, short-lived stream URL
$message->attachmentDownloadUrl($media);          // forces a download (attachment)
$message->attachmentPreviewUrl($media, 'responsive-640'); // a variant preview (images only)

• attachmentUrl() — zobrazenie v prehliadači; na podporujúcich diskoch predpodpísané, inak cez podpísanú streamovaciu routu media-library.
• attachmentDownloadUrl() — príznak stiahnutia je súčasťou podpisu, takže ho nemožno odstrániť.
• attachmentPreviewUrl() — len obrázky; pri inom súbore vyhodí MessageException.

Všetky tri prijímajú voliteľný názov variantu a používajú media.temporary_url_lifetime (inak predvolenú platnosť z media-library). Responzívny srcset() nad súkromnými médiami potrebuje podpísanú URL pre každú šírku, preto ho používajte len pri verejnej skupine.

Pomenovaný variant už musí byť vygenerovaný. responsive-640 existuje, až keď má obrázok aspoň 640 px na šírku (rebríček šírok nikdy nezväčšuje) a jeho varianty sa vygenerovali — pri odoslaní, pozri nižšie. Dovtedy attachmentUrl() aj attachmentPreviewUrl() vyhodia InvalidVariant z media-library; ak je zapnuté media.url_fallback_to_original, vrátia namiesto toho originál.

Varianty a upratovanie

Po odoslaní správy listener WarmMessageMediaVariants vo fronte spustí pre každú obrázkovú prílohu GenerateVariantsJob z media-library, takže náhľady sú pripravené, kým správa dorazí. Trvalé zmazanie správy (hard delete alebo prune) odstráni súbory príloh; soft delete (zrušenie odoslania) ich ponechá.

Konfigurácia

// config/messages.php
'media' => [
    'attachments_bucket'      => 'attachments', // media-library bucket name
    'disk'                    => env('MESSAGES_MEDIA_DISK', null),       // null = by visibility (below)
    'private_disk'            => env('MESSAGES_MEDIA_PRIVATE_DISK', 'local'), // private attachments when 'disk' is null
    'visibility'              => env('MESSAGES_MEDIA_VISIBILITY', 'private'), // 'private' | 'public' (else throws)
    'accepted_mime_types'     => [],            // [] = accept any file
    'max_file_size'           => null,          // bytes (>= 1); null = media default
    'responsive_widths'       => null,          // positive ints; null = media default ladder
    'warm_on_send'            => true,          // queue variant generation on send
    'temporary_url_lifetime'  => null,          // minutes (>= 1); null = media default
    'cleanup_on_force_delete' => true,          // remove files on hard delete / prune
],

Explicitne nastavený disk sa použije pre každú prílohu bez ohľadu na viditeľnosť, preto ho pri súkromných prílohách nechajte neverejný; private_disk môže ukazovať na akýkoľvek neverejný disk, napríklad súkromný S3 bucket. Preklep vo visibility, názov bucketu či disku, ktorý nie je reťazcom, prípadne nezmyselná veľkosť, šírka, platnosť či položka mime typu vyhodí InvalidConfigurationException — nikdy sa nepoužije náhradná hodnota. Prázdna hodnota (MESSAGES_MEDIA_DISK=) sa považuje za nenastavenú, takže platí predvolená.