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/v6)  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/v6/introduction)
- [ Postcardware ](https://spatie.be/docs/laravel-medialibrary/v6/postcardware)
- [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v6/requirements)
- [ Installation & setup ](https://spatie.be/docs/laravel-medialibrary/v6/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v6/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v6/changelog)
- [ About us ](https://spatie.be/docs/laravel-medialibrary/v6/about-us)

Basic usage
-----------

- [ Preparing your model ](https://spatie.be/docs/laravel-medialibrary/v6/basic-usage/preparing-your-model)
- [ Associating files ](https://spatie.be/docs/laravel-medialibrary/v6/basic-usage/associating-files)
- [ Retrieving media ](https://spatie.be/docs/laravel-medialibrary/v6/basic-usage/retrieving-media)
- [ Working with collections ](https://spatie.be/docs/laravel-medialibrary/v6/basic-usage/working-with-collections)

Converting images
-----------------

- [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v6/converting-images/defining-conversions)
- [ Retrieving converted images ](https://spatie.be/docs/laravel-medialibrary/v6/converting-images/retrieving-converted-images)
- [ Optimizing converted images ](https://spatie.be/docs/laravel-medialibrary/v6/converting-images/optimizing-converted-images)
- [ Regenerating images ](https://spatie.be/docs/laravel-medialibrary/v6/converting-images/regenerating-images)

Converting other file types
---------------------------

- [ Using image generators ](https://spatie.be/docs/laravel-medialibrary/v6/converting-other-file-types/using-image-generators)
- [ Creating a custom image generator ](https://spatie.be/docs/laravel-medialibrary/v6/converting-other-file-types/creating-a-custom-image-generator)

Advanced usage
--------------

- [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/working-with-multiple-filesystems)
- [ Generating custom urls ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/generating-custom-urls)
- [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/storing-media-specific-manipulations)
- [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/using-your-own-model)
- [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/using-a-custom-directory-structure)
- [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/ordering-media)
- [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/consuming-events)
- [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/overriding-the-default-filesystem-behaviour)
- [ Responding with media ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/responding-with-media)
- [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v6/advanced-usage/using-custom-properties)

API
---

- [ Adding files ](https://spatie.be/docs/laravel-medialibrary/v6/api/adding-files)
- [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v6/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)
```

### 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 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\Media
  *
  * @throws FileCannotBeAdded
  * @throws \Spatie\MediaLibrary\Exceptions\FileCannotBeAdded
  */
 public function toMediaCollectionOnCloudDisk(string $collectionName = 'default')
```