Pridávanie médií

MediaLibrary::for($model) obmedzí pridávanie na jedného vlastníka. Každá metóda add* vracia builder PendingFileAdd; terminálne toBucket() zapíše súbor a vráti Media. Zdroje pokrývajú každý tvar vstupu:

use RoundlyConsulting\MediaLibrary\Facades\MediaLibrary;

$media = MediaLibrary::for($user);

$media->add($request->file('avatar'))->toBucket('avatar');            // UploadedFile or local path
$media->addFromRequest('avatar')->toBucket('avatar');                 // request upload by key
$media->addFromUrl('https://example.com/poster.png')->toBucket('gallery');
$media->addFromDisk('incoming/doc.pdf', 's3')->toBucket('gallery');
$media->addFromString($bytes)->usingFileName('note.txt')->toBucket('gallery');
$media->addFromBase64($base64)->toBucket('gallery');
$media->addFromStream($resource)->usingFileName('upload.bin')->toBucket('gallery');

Skratka cez trait

Trait InteractsWithMedia ponúka tie isté pridania priamo na modeli — idú cez manažéra fasády, takže ich vidí aj MediaLibrary::fake():

$user->addMedia($request->file('avatar'))->toMediaBucket('avatar');
$user->addMediaFromRequest('avatar')->toMediaBucket('avatar');
$user->addMultipleMediaFromRequest(['a', 'b']);                       // PendingFileAdd[] (keys without a file skipped)
$user->addMediaFromUrl($url);  $user->addMediaFromDisk($path, 's3');
$user->addMediaFromString($bytes);  $user->addMediaFromBase64($b64);  $user->addMediaFromStream($resource);

Builder PendingFileAdd

Builderom pred terminálnym volaním nastavíte názov, vlastné vlastnosti, disky, viditeľnosť a ďalšie:

$media = MediaLibrary::for($user)->add($request->file('avatar'))
    ->usingName('Profile photo')                 // display name
    ->usingFileName('avatar.jpg')                // stored filename (made safe, see Upload safety)
    ->withCustomProperties(['alt' => 'Jane'])    // arbitrary metadata
    ->withProperty('source', 'signup')           // one property at a time
    ->useDisk('cold')                            // override the bucket/config original disk
    ->storingVariantsOnDisk('hot')               // override the bucket/config variants disk
    ->withVisibility('private')                  // override the bucket default
    ->onQueue('media')                           // queue any queued variants on this queue
    ->asDraft()                                  // store as an unbound draft
    ->toBucket('avatar');                        // terminal: returns Media (toMediaBucket() is the same)

Terminál súbor zvaliduje ešte pred akýmkoľvek zápisom — mime allowlist skupiny, jej limit veľkosti (maxFileSize(), inak media.max_file_size) a pri obrázkoch minDimensions() / maxDimensions() — a pri chybe vyhodí typovanú výnimku: FileUnacceptableForBucket, FileDoesNotExist, DiskDoesNotExist, MediaOwnerNotSaved (vlastník, ktorý ešte nebol uložený — okrem draftov), InvalidVisibility (withVisibility() s čímkoľvek iným než presne public alebo private, aj Private), FileCannotBeWritten (disk odmietol zápis; riadok sa neuloží) alebo RemoteFileRejected (URL, ktorú addFromUrl() odmietne — pozrite Bezpečnosť uploadu). Sú to tie isté limity, z ktorých vychádza MediaLibrary::rulesFor(), takže FormRequest a balík sa nikdy nerozídu.

Zdroj sa vždy len číta: lokálnu cestu, ktorú pridáte, balík nikdy nepresunie ani nezmaže — vždy uloží kópiu. Uploady, streamy aj súbory z disku sa kopírujú po častiach, nikdy sa nenačítajú do pamäte celé, a zobrazovaný názov sa skráti na 255 znakov, ktoré pojme stĺpec name.

Vo vlastnej transakcii

Pridanie zapíše súbory skôr, než sa rozhodne o vašej vlastnej DB::transaction(). Ak ju vrátite späť a s ňou aj nový riadok, pridanie súbory, ktoré zapísalo, opäť zmaže — originál aj varianty vygenerované počas pridania, na ktoromkoľvek disku skončili —, takže na disku nezostane súbor bez riadku:

• Deduplikovaný originál zdieľaný s existujúcim médiom zostane a súbor, ktorý má niektorý riadok média stále uložený ako originál, sa nikdy nezmaže.
• Vnorená DB::transaction(), ktorá sa vráti späť, zmaže len súbory pridaní v nej; potvrdená vnorená transakcia si ich ponechá až do konca vonkajšej a potvrdenie najvonkajšej transakcie ponechá všetky súbory.
• Frontované varianty sa odošlú až po potvrdení najvonkajšej transakcie, takže po vrátení späť žiadny nezostane.
• Zmazanie, ktoré počas vrátenia späť zlyhá, sa nahlási vášmu exception handleru a nikdy nenahradí výnimku, ktorá ho spôsobila; daný súbor na disku zostane.
• Testovacie traity RefreshDatabase a DatabaseTransactions z Laravelu vracajú svoju obaľujúcu transakciu späť s vypnutými eventmi, takže toto vrátenie súbory z pridaní v teste nikdy neodstráni.