URL, streaming a sťahovanie

Verejné médiá majú priame URL z disku — cez handle vlastníka alebo priamo na Media:

MediaLibrary::for($user)->url('avatar');          // first media's URL, the fallback, or ''
MediaLibrary::for($user)->url('avatar', 'thumb'); // first media's variant URL

$media->getUrl();          // original (public media)
$media->getUrl('thumb');   // a named variant (on the variants disk)

Súkromné a dočasné URL

Súkromné médiá verejné URL nemajú, preto použite dočasné URL: na podporujúcich diskoch (S3 a každý driver s temporaryUrl()) ho natívne podpíše, inak prejde na podpísanú streamovaciu routu Laravelu. Ak sa prehliadače k úložisku objektov dostanú cez iný pôvod ako aplikácia, použite disk driver presigned-s3 z balíka (nižšie), aby sa URL podpísala pre verejný pôvod. Bez zadanej platnosti sa použije temporary_url_default_lifetime. Veľké súbory sa streamujú efektívne vrátane obnoviteľných čiastočných sťahovaní:

// Private media has no public URL — getUrl() throws. Use a temporary URL:
MediaLibrary::for($user)->temporaryUrl('avatar', expiry: now()->addMinutes(10));
$media->getTemporaryUrl(now()->addMinutes(5));
$media->getTemporaryUrl(now()->addMinutes(5), 'thumb');
// presigned on S3-like disks, or a Laravel signed streaming route on local/cold disks

return $media->toResponse($request);              // stream inline (safe types), range-aware
return $media->toDownloadResponse('invoice.pdf'); // as an attachment

Streamovacia routa

Balík zaregistruje GET {prefix}/{media}/{variant?} s názvom media.stream. {media} sa viaže podľa UUID a routa spúšťa nakonfigurovaný middleware plus middleware signed od Laravelu, ktorý sa pripojí vždy; ?download=1 v podpísanej URL vráti súbor ako prílohu. Bez platného podpisu (alebo na diskoch s natívnym podpisovaním bez podpísanej URL) routa nič nevydá:

'stream' => [
    'enabled' => true,           // register the signed streaming route
    'route_prefix' => 'media',   // URI prefix
    'middleware' => ['web'],     // Laravel's 'signed' is always appended
],

Čo sa servíruje inline

Inline sa servírujú len typy, ktoré prehliadač zobrazí bez spúšťania čohokoľvek — rastrové obrázky, audio, video, PDF a obyčajný text. HTML, SVG, XML a všetky ostatné typy sa posielajú ako príloha a každá odpoveď nesie X-Content-Type-Options: nosniff a izolujúcu Content-Security-Policy, takže uložený súbor nikdy nespustí skript na pôvode vašej aplikácie. Variant sa servíruje s typom vlastného formátu. Nečitateľná alebo viacnásobná hlavička Range sa ignoruje (celý súbor, 200); rozsah za koncom súboru dostane 416.

Súkromné médiá potrebujú súkromný disk

->private() / withVisibility('private') nastaví viditeľnosť súboru — ACL objektu v S3 alebo režim 0600 na lokálnom disku. Nezastaví však webový server, ktorý disk servíruje priamo: predvolený disk public je cez symlink pod public/storage, takže súkromný súbor uložený na ňom sa dá stiahnuť z /storage/{uuid}/{file} všade, kde webový server beží pod používateľom PHP — a uuid je v každej podpísanej URL. Súkromné skupiny držte na disku, ktorý webový server neservíruje, napríklad na disku local od Laravelu (storage/app/private) alebo v súkromnom S3 buckete:

// Keep private buckets on a disk the web server does not serve.
$this->addMediaBucket('invoices')
    ->useDisk('local')   // storage/app/private — not symlinked under public/storage
    ->private();

Samostatný endpoint na podpisovanie — disk presigned-s3

Nasadenie v Kubernetes často ukladá médiá do úložiska objektov v klastri (http://rustfs:9000), ku ktorému sa prehliadače nedostanú; to isté úložisko dosiahnu cez verejný pôvod (https://media.example.com, ingress pred ním). Presigned URL teda musia uvádzať verejný pôvod, zatiaľ čo každé čítanie a zápis ide ďalej v rámci klastra. Driver s3 od Laravelu to nedokáže: SigV4 podpisuje host a jeho voľba temporary_url presmeruje URL na iný host až po podpísaní, takže úložisko každý odkaz odmietne. Balík preto registruje voliteľný disk driver presigned-s3 — disk ho zapne uvedením jeho názvu a všetky kľúče s3 platia ďalej:

// config/filesystems.php
'media' => [
    'driver' => 'presigned-s3',                        // instead of 's3'
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION'),
    'bucket' => env('AWS_BUCKET'),
    'endpoint' => env('AWS_ENDPOINT'),                 // in-cluster: http://rustfs:9000
    'use_path_style_endpoint' => true,
    'presign_endpoint' => env('AWS_PRESIGN_ENDPOINT'),  // public: https://media.example.com
    'visibility' => 'private',
],

• Bez presign_endpoint je disk štandardný S3 adaptér Laravelu, bajt po bajte — vrátane temporary_url, takže nastavenie s proxy, ktorá zachová host, funguje ďalej.
• S ním idú čítania, zápisy, exists(), delete() a ostatné operácie nezmenene na endpoint, zatiaľ čo temporaryUrl() a temporaryUploadUrl() pre verejný pôvod podpisuje druhý klient. Ten zdieľa s diskom prihlasovacie údaje (vrátane session tokenov, IRSA a web identity), región aj voľby klienta a nikdy neodošle požiadavku.
• url() vráti url disku + cestu, keď disk url nastavuje (CDN pred verejnými objektmi). Bez nej vyhodí DiskHasNoPublicUrl namiesto toho, aby URL zostavil z endpointu v klastri — médiá na takom disku držte súkromné a používajte dočasné URL.
• temporary_url spolu s presign_endpoint sa odmietne už pri vytváraní disku: jedno podpisuje pre verejný host, druhé mení host až po podpísaní. SigV4 obmedzuje platnosť presigned URL na sedem dní.
• S3 stack zostáva na vás: podobne ako driver s3 od Laravelu potrebuje disk league/flysystem-aws-s3-v3, ktorý balík len odporúča (suggest). Bez neho alebo s nepoužiteľným kľúčom presign vyhodí vytvorenie disku InvalidConfigurationException s názvom filesystems.disks.<disk>.<key> — nikdy s hodnotou — až pri prvom použití disku, nikdy pri štarte aplikácie.

V balíku sa nič nemení: getTemporaryUrl() aj MediaLibrary::for($model)->temporaryUrl() volajú temporaryUrl() disku, takže médiá na takom disku dostanú URL s verejným pôvodom. Ingress musí požiadavky do úložiska posielať s nezmenenou verejnou hlavičkou Host, pretože úložisko overuje podpis voči hostu, ktorý dostane; MinIO a RustFS v režime virtual-host navyše potrebujú mať ako doménu nastavený verejný host.