Adding files

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 FileAdders. 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 FileAdders. 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')