Adding files | laravel-medialibrary | Spatie SPATIE Laravel Media Library ======================== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-medialibrary](https://spatie.be/docs/laravel-medialibrary/v11) Api Adding files Version v11 v10 v9 v8 v7 v6 v4 v3 Other versions for crawler [v11](https://spatie.be/docs/laravel-medialibrary/v11) [v10](https://spatie.be/docs/laravel-medialibrary/v10) [v9](https://spatie.be/docs/laravel-medialibrary/v9) [v8](https://spatie.be/docs/laravel-medialibrary/v8) [v7](https://spatie.be/docs/laravel-medialibrary/v7) [v6](https://spatie.be/docs/laravel-medialibrary/v6) [v4](https://spatie.be/docs/laravel-medialibrary/v4) [v3](https://spatie.be/docs/laravel-medialibrary/v3) Adding files - [ Introduction ](https://spatie.be/docs/laravel-medialibrary/v11/introduction) - [ Support us ](https://spatie.be/docs/laravel-medialibrary/v11/support-us) - [ Base installation ](https://spatie.be/docs/laravel-medialibrary/v11/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v11/questions-issues) - [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v11/requirements) - [ Upgrading ](https://spatie.be/docs/laravel-medialibrary/v11/upgrading) - [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v11/changelog) - [ Troubleshooting ](https://spatie.be/docs/laravel-medialibrary/v11/troubleshooting) - [ About us ](https://spatie.be/docs/laravel-medialibrary/v11/about-us) Basic usage ----------- - [ Preparing your model ](https://spatie.be/docs/laravel-medialibrary/v11/basic-usage/preparing-your-model) - [ Associating files ](https://spatie.be/docs/laravel-medialibrary/v11/basic-usage/associating-files) - [ Retrieving media ](https://spatie.be/docs/laravel-medialibrary/v11/basic-usage/retrieving-media) Working with media collections ------------------------------ - [ Simple media collections ](https://spatie.be/docs/laravel-medialibrary/v11/working-with-media-collections/simple-media-collections) - [ Defining media collections ](https://spatie.be/docs/laravel-medialibrary/v11/working-with-media-collections/defining-media-collections) Converting images ----------------- - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v11/converting-images/defining-conversions) - [ Retrieving converted images ](https://spatie.be/docs/laravel-medialibrary/v11/converting-images/retrieving-converted-images) - [ Optimizing converted images ](https://spatie.be/docs/laravel-medialibrary/v11/converting-images/optimizing-converted-images) - [ Regenerating images ](https://spatie.be/docs/laravel-medialibrary/v11/converting-images/regenerating-images) Responsive images ----------------- - [ Getting started with responsive images ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/getting-started-with-responsive-images) - [ Using your own width calculator ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/using-your-own-width-calculator) - [ Customizing the rendered HTML ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/customizing-the-rendered-html) - [ Generating your own tiny placeholder ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/generating-your-own-tiny-placeholder) - [ Responsive images demo ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/demo) Converting other file types --------------------------- - [ Using image generators ](https://spatie.be/docs/laravel-medialibrary/v11/converting-other-file-types/using-image-generators) - [ Creating a custom image generator ](https://spatie.be/docs/laravel-medialibrary/v11/converting-other-file-types/creating-a-custom-image-generator) Downloading media ----------------- - [ Downloading a single file ](https://spatie.be/docs/laravel-medialibrary/v11/downloading-media/downloading-a-single-file) - [ Downloading multiple files ](https://spatie.be/docs/laravel-medialibrary/v11/downloading-media/downloading-multiple-files) Advanced usage -------------- - [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/working-with-multiple-filesystems) - [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-custom-properties) - [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/storing-media-specific-manipulations) - [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-your-own-model) - [ Outputting media ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/outputting-media) - [ Rendering media ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/rendering-media) - [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-a-custom-directory-structure) - [ Using a custom file removal strategy ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-a-custom-file-removal-strategy) - [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/ordering-media) - [ Using a custom media downloader ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-a-custom-media-downloader) - [ Moving media ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/moving-media) - [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/consuming-events) - [ Attaching media in mails ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/attaching-media-in-mails) - [ Generating custom URLs ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/generating-custom-urls) - [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/overriding-the-default-filesystem-behaviour) - [ Naming generated files ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/naming-files) - [ Disable CDN ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/disable-cdn) - [ Customising Database Connections ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/customising-database-connections) API --- - [ Adding files ](https://spatie.be/docs/laravel-medialibrary/v11/api/adding-files) - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v11/api/defining-conversions) Adding files ============ ### On this page 1. [ Starting methods ](#content-starting-methods) 2. [ Middle methods ](#content-middle-methods) 3. [ Finishing methods ](#content-finishing-methods) Adding a file to the media library is easy. Just pick one of the starting methods, optionally add some of the middle methods and finish with a finishing method. All start and middle methods are chainable. For example: ``` $yourModel ->addMedia($pathToFile) //starting method ->withCustomProperties(['mime-type' => 'image/jpeg']) //middle method ->preservingOriginal() //middle method ->toMediaCollection(); //finishing method ``` Starting methods -------------------------------------------------------------------------------------------------------- ### addMedia ``` /** * Add a file to the media library. The file will be removed from * its original location. * * @param string|\Symfony\Component\HttpFoundation\File\UploadedFile $file * * @return \Spatie\MediaLibrary\MediaCollections\FileAdder */ public function addMedia($file) ``` ### addMediaFromUrl This method only accepts URLs that start with `http://` or `https://` ``` /** * Add a remote file to the media library. * * @param string $url * * @return mixed * * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded */ public function addMediaFromUrl(string $url) ``` **Security note.** `addMediaFromUrl` fetches whatever URL you pass to it from your server. It validates only that the URL starts with `http://` or `https://`, not that the destination is safe to reach. Passing user supplied URLs directly therefore exposes your application to server side request forgery (SSRF), letting an attacker make requests to internal hosts, RFC 1918 ranges, loopback, or cloud metadata endpoints (such as `http://169.254.169.254/`). Only call `addMediaFromUrl` with URLs you control, or that you have validated against an allowlist of hosts. ### addMediaFromDisk ``` /** * Add a file from the given disk. * * @param string $key * @param string $disk * * @return \Spatie\MediaLibrary\MediaCollections\FileAdder */ public function addMediaFromDisk(string $key, string $disk = null): FileAdder ``` ### addMediaFromRequest ``` /** * Add file from the current request to the media library. * * @param string $keyName * * @return \Spatie\MediaLibrary\MediaCollections\FileAdder * * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded */ public function addMediaFromRequest(string $keyName): FileAdder ``` ### addMultipleMediaFromRequest ``` /** * Add multiple files from the current request to the media library. * * @param string[] $keys * * @return Collection * * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded */ public function addMultipleMediaFromRequest(array $keyNames): Collection ``` Please note the return type of `addMultipleMediaFromRequest` is a collection of `FileAdder`s. This means you'll have to loop over every `FileAdder` to use any of the middle methods. For example: ``` $fileAdders = $this->model ->addMultipleMediaFromRequest(['file-one', 'file-two']) ->each(function ($fileAdder) { $fileAdder->toMediaCollection(); }); ``` ### addAllMediaFromRequest ``` /** * Add all files from the current request to the media library. * * @return Collection * * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded */ public function addAllMediaFromRequest(): Collection ``` Please note the return type of `addAllMediaFromRequest` is a Collection of `FileAdder`s. This means you'll have to loop over every `FileAdder` to use any of the middle methods. See the `addMultipleMediaFromRequest` method above for an example. ### addMediaFromBase64 ``` /** * Add a base64 encoded file to the media library. * * @param string $base64data * @param string|array ...$allowedMimeTypes * * @throws InvalidBase64Data * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded * * @return \Spatie\MediaLibrary\MediaCollections\FileAdder */ public function addMediaFromBase64(string $base64data, ...$allowedMimeTypes): FileAdder ``` ### addMediaFromString ``` /** * Add a file to the media library that contains the given string. * * @param string string * * @return \Spatie\MediaLibrary\MediaCollections\FileAdder */ public function addMediaFromString(string $string): FileAdder ``` The file will be named 'text.txt' by default. A specific file name can be set using `usingFileName` ``` $model ->addMediaFromString('my string') ->usingFileName('custom-filename.txt') ->toMediaCollection(); ``` ### addMediaFromStream ``` /** * Add a file to the media library from a stream. * * @param $stream * * @return \Spatie\MediaLibrary\MediaCollections\FileAdder */ public function addMediaFromStream($stream): FileAdder ``` The file will be named 'text.txt' by default. A specific file name can be set using `usingFileName` ``` $model ->addMediaFromStream($stream) ->usingFileName('custom-filename.txt') ->toMediaCollection(); ``` ### copyMedia ``` /** * Copy a file to the media library. * * @param string|\Symfony\Component\HttpFoundation\File\UploadedFile $file * * @return \Spatie\MediaLibrary\MediaCollections\FileAdder */ public function copyMedia($file) ``` Middle methods -------------------------------------------------------------------------------------------------- ### preserveOriginal ``` /** * When adding the file to the media library, the original file * will be preserved. * * @return $this */ public function preservingOriginal() ``` ### usingName ``` /** * Set the name of the media object. * * @param $name * * @return $this */ public function usingName($name) ``` ### setName This is an alias for `usingName` ### usingFileName ``` /** * Set the name of the file that is stored on disk. * * @param $fileName * * @return $this */ public function usingFileName($fileName) ``` ### setFileName This is an alias for `usingFileName` ### withCustomProperties ``` /** * Set the metadata. * * @param array $customProperties * * @return $this */ public function withCustomProperties(array $customProperties) ``` Finishing methods ----------------------------------------------------------------------------------------------------------- ### toMediaCollection ``` /** * Set the target media collection to default. * Will also start the import process. * * @param string $collectionName * @param string $diskName * * @return Media * * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded */ public function toMediaCollection($collectionName = 'default', $diskName = '') ``` ### toMediaCollectionOnCloudDisk This function does almost the same as `toMediaCollection`. It'll store all media on the disk configured in the `cloud` key of `config/filesystems.php` ``` /** * @param string $collectionName * * @return \Spatie\MediaLibrary\MediaCollections\Models\Media * * @throws FileCannotBeAdded * @throws \Spatie\MediaLibrary\MediaCollections\Exceptions\FileCannotBeAdded */ public function toMediaCollectionOnCloudDisk(string $collectionName = 'default') ``` A good match? ------------- ### What we do best - All things Laravel - Custom frontend components - Building APIs - AI-powered features - Simplifying things - Clean solutions - Integrating services ### Not our cup of tea - WordPress themes - Cutting corners - Free mockups to win a job - "Just execute the briefing" In short: we'd like to be a **substantial part** of your project. [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)