Retrieving media | laravel-medialibrary | Spatie

 SPATIE

  Laravel Media Library
========================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-medialibrary](https://spatie.be/docs/laravel-medialibrary/v10)  Basic-usage  Retrieving media

 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/v10/introduction)
- [ Support us ](https://spatie.be/docs/laravel-medialibrary/v10/support-us)
- [ Base installation ](https://spatie.be/docs/laravel-medialibrary/v10/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v10/questions-issues)
- [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v10/requirements)
- [ Upgrading ](https://spatie.be/docs/laravel-medialibrary/v10/upgrading)
- [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v10/changelog)
- [ Troubleshooting ](https://spatie.be/docs/laravel-medialibrary/v10/troubleshooting)
- [ About us ](https://spatie.be/docs/laravel-medialibrary/v10/about-us)

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

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

Working with media collections
------------------------------

- [ Simple media collections ](https://spatie.be/docs/laravel-medialibrary/v10/working-with-media-collections/simple-media-collections)
- [ Defining media collections ](https://spatie.be/docs/laravel-medialibrary/v10/working-with-media-collections/defining-media-collections)

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

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

Handling uploads with Media Library Pro
---------------------------------------

- [ Introduction ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/introduction)
- [ Installation ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/installation)
- [ Processing uploads on the server ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/processing-uploads-on-the-server)
- [ Handling uploads with Livewire 2 ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/handling-uploads-with-livewire-2)
- [ Handling uploads with Livewire 3 ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/handling-uploads-with-livewire-3)
- [ Handling uploads with Vue ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/handling-uploads-with-vue)
- [ Creating custom Vue components ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/creating-custom-vue-components)
- [ Handling uploads with React ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/handling-uploads-with-react)
- [ Creating custom React components ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/creating-custom-react-components)
- [ Customizing CSS ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/customizing-css)
- [ Upgrading ](https://spatie.be/docs/laravel-medialibrary/v10/handling-uploads-with-media-library-pro/upgrading)

Responsive images
-----------------

- [ Getting started with responsive images ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/getting-started-with-responsive-images)
- [ Using your own width calculator ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/using-your-own-width-calculator)
- [ Customizing the rendered HTML ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/customizing-the-rendered-html)
- [ Generating your own tiny placeholder ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/generating-your-own-tiny-placeholder)
- [ Responsive images demo ](https://spatie.be/docs/laravel-medialibrary/v10/responsive-images/demo)

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

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

Downloading media
-----------------

- [ Downloading a single file ](https://spatie.be/docs/laravel-medialibrary/v10/downloading-media/downloading-a-single-file)
- [ Downloading multiple files ](https://spatie.be/docs/laravel-medialibrary/v10/downloading-media/downloading-multiple-files)

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

- [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/working-with-multiple-filesystems)
- [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-custom-properties)
- [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/storing-media-specific-manipulations)
- [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-your-own-model)
- [ Outputting media ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/outputting-media)
- [ Rendering media ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/rendering-media)
- [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-a-custom-directory-structure)
- [ Using a custom file removal strategy ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-a-custom-file-removal-strategy)
- [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/ordering-media)
- [ Using a custom media downloader ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/using-a-custom-media-downloader)
- [ Moving media ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/moving-media)
- [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/consuming-events)
- [ Attaching media in mails ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/attaching-media-in-mails)
- [ Generating custom URLs ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/generating-custom-urls)
- [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/overriding-the-default-filesystem-behaviour)
- [ Naming generated files ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/naming-files)
- [ Disable CDN ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/disable-cdn)
- [ Customising Database Connections ](https://spatie.be/docs/laravel-medialibrary/v10/advanced-usage/customising-database-connections)

API
---

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

Retrieving media
================

###  On this page

1. [ Are you a visual learner? ](#content-are-you-a-visual-learner)

To retrieve files you can use the `getMedia`-method:

```
$mediaItems = $yourModel->getMedia();
```

To retrieve files from all collections you can use the `getMedia`-method with `*`:

```
$mediaItems = $yourModel->getMedia("*");
```

The method returns a collection of `Media`-objects.

You can retrieve the URL and path to the file associated with the `Media`-object using `getUrl`, `getTemporaryUrl` (for S3 only) and `getPath`:

```
$publicUrl = $mediaItems[0]->getUrl();
$publicFullUrl = $mediaItems[0]->getFullUrl(); // URL including domain
$fullPathOnDisk = $mediaItems[0]->getPath();
$temporaryS3Url = $mediaItems[0]->getTemporaryUrl(Carbon::now()->addMinutes(5));
```

If you want to retrieve versioned media URLs, for example when needing cache busting, you can enable versioning by setting the `version_urls` config value to `true` in your `media-library.php` config file. The `getUrl()` and `getFullUrl()` functions will return the URL with a version string based on the `updated_at` column of the media model.

Since retrieving the first media and the URL for the first media for an object is such a common scenario, the `getFirstMedia` and `getFirstMediaUrl` convenience-methods are also provided:

```
$media = $yourModel->getFirstMedia();
$url = $yourModel->getFirstMediaUrl();
```

An instance of `Media` also has a name, by default its filename:

```
echo $mediaItems[0]->name; // Display the name

$mediaItems[0]->name = 'new name';
$mediaItems[0]->save(); // The new name gets saved.
```

The name of a `Media` instance can be changed when it's added to the media library:

```
$yourModel
   ->addMedia($pathToFile)
   ->usingName('new name')
   ->toMediaCollection();
```

The name of the uploaded file can be changed via the media-object:

```
$mediaItems[0]->file_name = 'newFileName.jpg';
$mediaItems[0]->save(); // Saving will also rename the file on the filesystem.
```

The name of the uploaded file can also be changed when it gets added to the media-library:

```
$yourModel
   ->addMedia($pathToFile)
   ->usingFileName('otherFileName.txt')
   ->toMediaCollection();
```

You can sanitize the filename using a callable:

```
$yourModel
   ->addMedia($pathToFile)
   ->sanitizingFileName(function($fileName) {
      return strtolower(str_replace(['#', '/', '\\', ' '], '-', $fileName));
   })
   ->toMediaCollection();
```

You can also retrieve the size of the file via `size` and `human_readable_size` :

```
$mediaItems[0]->size; // Returns the size in bytes
$mediaItems[0]->human_readable_size; // Returns the size in a human readable format (eg. 1,5 MB)
```

An instance of `Media` also contains the mime type of the file.

```
$mediaItems[0]->mime_type; // Returns the mime type
```

You can remove something from the library by simply calling `delete` on an instance of `Media`:

```
$mediaItems[0]->delete();
```

When a `Media` instance gets deleted all related files will be removed from the filesystem.

Deleting a model with associated media will also delete all associated files. If you use soft deletes, the associated files won't be deleted.

```
$yourModel->delete(); // all associated files will be deleted as well
```

You may delete a model without removing associated media by calling the `deletePreservingMedia` method instead of `delete`.

```
$yourModel->deletePreservingMedia(); // all associated files will be preserved
```

If you want to remove all associated media in a specific collection you can use the `clearMediaCollection` method. It also accepts the collection name as an optional parameter:

```
$yourModel->clearMediaCollection(); // all media in the "default" collection will be deleted

$yourModel->clearMediaCollection('images'); // all media in the images collection will be deleted
```

Also, there is a `clearMediaCollectionExcept` method which can be useful if you want to remove only few or some selected media in a collection. It accepts the collection name as the first argument and the media instance or collection of media instances which should not be removed as the second argument:

```
$yourModel->clearMediaCollectionExcept('images', $yourModel->getFirstMedia()); // This will remove all associated media in the 'images' collection except the first media
```

Are you a visual learner?
---------------------------------------------------------------------------------------------------------------------------------

Here's are a couple of videos on adding and retrieving media.

Want to see more videos like these? Check out our [free video course on how to use Laravel Media Library](https://spatie.be/courses/discovering-laravel-media-library).