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/v7) Api Adding files Version v11 v10 v9 v8 v7 v6 v5 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) [v5](https://spatie.be/docs/laravel-medialibrary/v5) [v4](https://spatie.be/docs/laravel-medialibrary/v4) [v3](https://spatie.be/docs/laravel-medialibrary/v3) - [ Introduction ](https://spatie.be/docs/laravel-medialibrary/v7/introduction) - [ Support us ](https://spatie.be/docs/laravel-medialibrary/v7/support-us) - [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v7/requirements) - [ Installation & setup ](https://spatie.be/docs/laravel-medialibrary/v7/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v7/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v7/changelog) - [ About us ](https://spatie.be/docs/laravel-medialibrary/v7/about-us) Basic usage ----------- - [ Preparing your model ](https://spatie.be/docs/laravel-medialibrary/v7/basic-usage/preparing-your-model) - [ Associating files ](https://spatie.be/docs/laravel-medialibrary/v7/basic-usage/associating-files) - [ Retrieving media ](https://spatie.be/docs/laravel-medialibrary/v7/basic-usage/retrieving-media) Working with media collections ------------------------------ - [ Simple media collections ](https://spatie.be/docs/laravel-medialibrary/v7/working-with-media-collections/simple-media-collections) - [ Defining media collections ](https://spatie.be/docs/laravel-medialibrary/v7/working-with-media-collections/defining-media-collections) Converting images ----------------- - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v7/converting-images/defining-conversions) - [ Retrieving converted images ](https://spatie.be/docs/laravel-medialibrary/v7/converting-images/retrieving-converted-images) - [ Optimizing converted images ](https://spatie.be/docs/laravel-medialibrary/v7/converting-images/optimizing-converted-images) - [ Regenerating images ](https://spatie.be/docs/laravel-medialibrary/v7/converting-images/regenerating-images) Responsive images ----------------- - [ Getting started with responsive images ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/getting-started-with-responsive-images) - [ Using your own width calculator ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/using-your-own-width-calculator) - [ Customizing the rendered html ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/customizing-the-rendered-html) - [ Generating your own tiny placeholder ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/generating-your-own-tiny-placeholder) - [ Responsive images demo ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/demo) Downloading media ----------------- - [ Downloading a single file ](https://spatie.be/docs/laravel-medialibrary/v7/downloading-media/downloading-a-single-file) - [ Downloading multiple files ](https://spatie.be/docs/laravel-medialibrary/v7/downloading-media/downloading-multiple-files) Converting other file types --------------------------- - [ Using image generators ](https://spatie.be/docs/laravel-medialibrary/v7/converting-other-file-types/using-image-generators) - [ Creating a custom image generator ](https://spatie.be/docs/laravel-medialibrary/v7/converting-other-file-types/creating-a-custom-image-generator) Advanced usage -------------- - [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/working-with-multiple-filesystems) - [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/using-custom-properties) - [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/storing-media-specific-manipulations) - [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/using-your-own-model) - [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/using-a-custom-directory-structure) - [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/ordering-media) - [ Moving media ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/moving-media) - [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/consuming-events) - [ Generating custom urls ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/generating-custom-urls) - [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/overriding-the-default-filesystem-behaviour) API --- - [ Adding files ](https://spatie.be/docs/laravel-medialibrary/v7/api/adding-files) - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v7/api/defining-conversions) You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command: ` composer show spatie/laravel-medialibrary ` 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 medialibrary 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 medialibrary. The file will be removed from * its original location. * * @param string|\Symfony\Component\HttpFoundation\File\UploadedFile $file * * @return \Spatie\MediaLibrary\FileAdder\FileAdder */ public function addMedia($file) ``` ### addMediaFromUrl ``` /** * Add a remote file to the medialibrary. * * @param string $url * * @return mixed * * @throws \Spatie\MediaLibrary\Exceptions\FileCannotBeAdded */ public function addMediaFromUrl(string $url) ``` ### addMediaFromDisk ``` /** * Add a file from the given disk. * * @param string $key * @param string $disk * * @return \Spatie\MediaLibrary\FileAdder\FileAdder */ public function addMediaFromDisk(string $key, string $disk = null): FileAdder ``` ### addMediaFromRequest ``` /** * Add file from the current request to the medialibrary. * * @param string $keyName * * @return \Spatie\MediaLibrary\FileAdder\FileAdder * * @throws \Spatie\MediaLibrary\Exceptions\FileCannotBeAdded */ public function addMediaFromRequest(string $keyName): FileAdder ``` ### addMultipleMediaFromRequest ``` /** * Add multiple files from the current request to the medialibrary. * * @param string[] $keys * * @return Collection * * @throws \Spatie\MediaLibrary\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 medialibrary. * * @return Collection * * @throws \Spatie\MediaLibrary\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 medialibrary. * * @param string $base64data * @param string|array ...$allowedMimeTypes * * @throws InvalidBase64Data * @throws \Spatie\MediaLibrary\Exceptions\FileCannotBeAdded * * @return \Spatie\MediaLibrary\FileAdder\FileAdder */ public function addMediaFromBase64(string $base64data, ...$allowedMimeTypes): FileAdder ``` ### copyMedia ``` /** * Copy a file to the medialibrary. * * @param string|\Symfony\Component\HttpFoundation\File\UploadedFile $file * * @return \Spatie\MediaLibrary\FileAdder\FileAdder */ public function copyMedia($file) ``` Middle methods -------------------------------------------------------------------------------------------------- ### preserveOriginal ``` /** * When adding the file to the medialibrary, 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\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\Models\Media * * @throws FileCannotBeAdded * @throws \Spatie\MediaLibrary\Exceptions\FileCannotBeAdded */ public function toMediaCollectionOnCloudDisk(string $collectionName = 'default') ```