Every two weeks I send out a newsletter containing lots of interesting stuff for the modern PHP developer. You can expect quick tips, links to interesting tutorials, opinions and packages. Want to learn the cool stuff? Then sign up now!

A medialibrary package for Laravel 5

At Spatie all our greenfield projects are powered by custom built CMS based on Laravel 5. An important part of the CMS is the medialibrary-component. It handles how uploaded files are associated with models. My intern and I recently took the time to release our medialibrary as a package on GitHub.

Basic usage

Installing the medialibrary in your project is easy. Just install the service provider and facade, publish the config and migration. Then run the migrations and let your models implement a trait provided by the package. Easy peasy.

Adding a file to the media library in a so-called “collection” is very simple.

$collectionName = ‘myFirstCollection’
$newsItem = News::find(1);
MediaLibrary::add($pathToAFile, $newsItem, $collectionName);

Adding a file will move it to a directory managed by the medialibrary.

To retrieve files you can use the getCollection-method:

$mediaItems = MediaLibrary::getCollection($newsItem, $collectionName);

The method returns an array with Media-objects that are in the collection for the given model.

You can use the Media-object to retrieve the URL to the item:

$publicURL = $mediaItems[0]->getURL(‘original’);

You can remove something from the library by passing the a media id to the remove method of the facade:


If you delete a record all related files will be removed from the filesystem.

//all associated files will be deleted as well

Using a facade works pretty good, but in my mind using the methods provided by the trait are more readable:

$newsItem = News::find(2);
$collectionName = ‘anotherFineCollection’;
$newsItem->addMedia($pathToAFile, $collectionName);

$mediaItems = $newsMedia->getMedia($collectionName);
$publicURL = $mediaItems[0]->getURL(‘original’);


Generating images

In addition to just storing the relation between a file and a model, the media library store manipulated images. Imagine you are making a site with news items. On the list view you want to show a small thumb, on the detail page you want to display a bigger image.

On your model you can specify which manipulations should be stored when adding an image for that model to the media library:

//in your news model
public static function getImageProfileProperties()
return [
‘list’=> [‘w’ => 200, ‘h’ => 200],
‘detail’=> [‘w’ => 1600, ‘h’ => 800],

Internally the medialibrary uses Glide to manipulate images. You can use any of the parameters provided in their image API. By default image manipulations will be performed on the default Laravel queue.

You can retrieve the URL’s to the derived images like this

Closing notes

Though the package provides some very specific functionality I believe it’s fairly easy to use. The main benefit for my coworkers and me is that we can leverage Composer to update the medialibrary all the sites of our clients.

As it stands right now there are no plans to open source our CMS, but you can already find lots of it’s components on GitHub:

Freek Van der Herten is a partner and developer at Spatie, an Antwerp based company that specializes in creating web apps with Laravel. After hours he writes about modern PHP and Laravel on this blog. When not coding he’s probably rehearsing with his kraut rock band. He loves waffles and butterflies.
  • Thanks for sharing I think it’s great 🙂 I’d definitely use that in future projects !