★ Laravel-medialibrary v7 preview: media collections
Tags: php, laravel
Published: 2020-01-02 22:53:39

---
title: ★ Laravel-medialibrary v7 preview: media collections
published: true
date: 2017-12-18 07:57:25 UTC
tags: php, laravel
canonical_url: https://freek.dev/934-laravel-medialibrary-v7-preview-media-collections
---

[laravel-medialibrary](https://docs.spatie.be/laravel-medialibrary/) is a package that can help handle media in a Laravel application. It can [organise your files across multiple filesystems](https://docs.spatie.be/laravel-medialibrary/v6/advanced-usage/working-with-multiple-filesystems), [generate thumbnails](https://docs.spatie.be/laravel-medialibrary/v6/converting-images/defining-conversions), [optimize images](https://docs.spatie.be/laravel-medialibrary/v6/converting-images/optimizing-converted-images) and much much more.

Like mentioned before on this blog my team and I are currently creating a new major version, v7, that adds a lot of awesome features such as [responsive images](https://twitter.com/freekmurze/status/939161592725409796), vue components to assist with uploading, ... Last week you got a preview of [multi file downloads](/laravel-medialibrary-v7-preview-multi-file-downloads), ... This week we are going to look at some improvements to defining media collections.

## What are media collections? #

Media collections already exist in the current version of the medialibrary. They allow you to put different types of files in their own collection.

Let's associate some media:

```
$newsItem = News::find(1);
$newsItem->addMedia($pathToImage)->toMediaCollection('images');
$newsItem->addMedia($pathToAnotherImage)->toMediaCollection('images');
$newsItem->addMedia($pathToPdfFile)->toMediaCollection('downloads');
$newsItem->addMedia($pathToAnExcelFile)->toMediaCollection('downloads');
```

All media in a specific collection can be retrieved like this:

```
// will return media instances for all files in the images collection
$newsItem->getMedia('images');

// will returns media instance for all files in the downloads collection
$newsItem->getMedia('downloads');
```

## New functionalities in v7 #

In v7 a media collection can be more than just a name to group files. By defining a media collection in your model you can add certain behaviours to collections.

To get started with media collections add a function called `registerMediaCollections` to [your prepared model](https://docs.spatie.be/laravel-medialibrary/v7/basic-usage/preparing-your-model). Inside that function you can use `addMediaCollection` to start a media collection.

```
// in your model

public function registerMediaCollections()
{
    $this->addMediaCollection('my-collection')
        //add options
        ...

    // you can define as much collections as needed
    $this->addMediaCollection('my-other-collection')
        //add options
        ...
}
```

### Only allow certain files in a collection #

You can pass a callback to `acceptsFile` that will check if a file is allowed into the collection. In this example we only accept `jpeg` files:

```
use Spatie\MediaLibrary\File;
...
public function registerMediaCollections()
{
    $this
        ->addMediaCollection('only-jpegs-please')
        ->acceptsFile(function (File $file) {
            return $file->mimeType === 'image/jpeg';
        });
}
```

This will succeed:

```
$yourModel->addMedia('beautiful.jpg')->toMediaCollection('only-jpegs-please');
```

This will throw a `Spatie\MediaLibrary\Exceptions\FileCannotBeAdded\FileUnacceptableForCollection` exception:

```
$yourModel->addMedia('ugly.ppt')->toMediaCollection('only-jpegs-please');
```

### Using a specific disk #

You can ensure that files added to a collection are automatically added to a certain disk.

```
// in your model

public function registerMediaCollections()
{
    $this
       ->addMediaCollection('big-files')
       ->useDisk('s3');
}
```

When adding a file to `my-collection` it will be stored on the `s3` disk.

```
$yourModel->addMedia($pathToFile)->toMediaCollection('big-files');
```

You can still specify the disk name manually when adding media. In this example the file will be stored on `alternative-disk` instead of `s3`.

```
$yourModel->addMedia($pathToFile)->toMediaCollection('big-files', 'alternative-disk');
```

### Single file collections #

If you want a collection to hold only one file you can use `singleFile` on the collection. A good use case for this would be an avatar collection on a `User` model. In most cases you'd want to have a user to only have one `avatar`.

```
// in your model

public function registerMediaCollections()
{
    $this
        ->addMediaCollection('avatar')
        ->singleFile();
}
```

The first time you add a file to the collection it will be stored as usual.

```
$yourModel->add($pathToImage)->toMediaCollection('avatar');
$yourModel->getMedia('avatar')->count(); // returns 1
$yourModel->getFirstUrl('avatar'); // will return an url to the `$pathToImage` file
```

When adding another file to a single file collection the first one will be deleted.

```
// this will remove other files in the collection
$yourModel->add($anotherPathToImage)->toMediaCollection('avatar');
$yourModel->getMedia('avatar')->count(); // returns 1
$yourModel->getFirstUrl('avatar'); // will return an url to the `$anotherPathToImage` file
```

### Registering media conversions #

It's recommended that your first read the section on [converting images](https://docs.spatie.be/laravel-medialibrary/v7/converting-images/defining-conversions) before reading the following paragraphs.

Normally image conversions are registered inside the `registerMediaConversions` function on your model. However, images conversions can also be registered inside media collections.

```
public function registerMediaCollections()
{
    $this
        ->addMediaCollection('my-collection')
        ->registerMediaConversions(function (Media $media) {
            $this
                ->addMediaConversion('thumb')
                ->width(100)
                ->height(100);
        });
}
```

When adding an image to `my-collection` a thumbnail that fits inside 100x100 will be created.

```
$yourModel->add($pathToImage)->toMediaCollection('my-collection');

$yourModel->getFirstMediaUrl('thumb') // returns an url to a 100x100 version of the added image.
```

Take a look at the [defining conversions section](https://docs.spatie.be/laravel-medialibrary/v7/converting-images/defining-conversions) to learn all the functions you can tack on to `addMediaConversion`.

## In closing #

These improvements are coming to v7 of laravel-medialibrary. v7 will probably be released around February - March 2018. Of course you can start using [v6 of laravel-medialibrary](https://docs.spatie.be/laravel-medialibrary/v6/) right now.