Associate files with Eloquent models
Latest commit 588ea0e Jan 20, 2017 @freekmurze freekmurze committed on GitHub Merge pull request #444 from ethaizone/patch-1
Fix fopen mode parameter to be read only.

Associate files with Eloquent models

Latest Version Software License Build Status SensioLabsInsight Quality Score StyleCI Total Downloads

This Laravel >=5.1 and Lumen compatible package can associate all sorts of files with Eloquent models. It provides a simple API to work with. To learn all about it, head over to the extensive documention.

Here are a few short examples of what you can do:

$newsItem = News::find(1);

It can handle your uploads directly:


Want to store some large files on another filesystem? No problem:

$newsItem->addMedia($smallFile)->toCollectionOnDisk('downloads', 'local');
$newsItem->addMedia($bigFile)->toCollectionOnDisk('downloads', 's3');

The storage of the files is handled by Laravel's Filesystem, so you can use any filesystem you like. Additionally the package can create image manipulations on images and pdfs that have been added in the medialibrary.

Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.


You'll find the documentation on

Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for improving the media library? Feel free to create an issue on GitHub, we'll try to address it as soon as possible.

If you've found a bug regarding security please mail instead of using the issue tracker.


To create derived images GD should be installed on your server. For the creation of thumbnails of svg's or pdf's you should also install Imagick.


You're free to use this package (it's MIT-licensed), but if it makes it to your production environment you are required to send us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.

The best postcards will get published on the open source page on our website.


You can install this package via composer using this command:

composer require spatie/laravel-medialibrary

Next, you must install the service provider:

// config/app.php
'providers' => [

You can publish the migration with:

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"

After the migration has been published you can create the media-table by running the migrations:

php artisan migrate

You can publish the config-file with:

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="config"

This is the contents of the published config file:

return [

     * The filesystems on which to store added files and derived images by default. Choose
     * one or more of the filesystems you configured in app/config/filesystems.php
    'defaultFilesystem' => 'media',

     * The maximum file size of an item in bytes. Adding a file
     * that is larger will result in an exception.
    'max_file_size' => 1024 * 1024 * 10,

     * This queue will be used to generate derived images.
     * Leave empty to use the default queue.
    'queue_name' => '',

     * The class name of the media model to be used.
    'media_model' => Spatie\MediaLibrary\Media::class,

     * When urls to files get generated this class will be called. Leave empty
     * if your files are stored locally above the site root or on s3.
    'custom_url_generator_class' => null,

     * The class that contains the strategy for determining a media file's path.
    'custom_path_generator_class' => null,

    's3' => [
         * The domain that should be prepended when generating urls.
        'domain' => '',

    'remote' => [
         * Any extra headers that should be included when uploading media to
         * a remote disk. Even though supported headers may vary between
         * different drivers, a sensible default has been provided.
         * Supported by S3: CacheControl, Expires, StorageClass,
         * ServerSideEncryption, Metadata, ACL, ContentEncoding
        'extra_headers' => [
            'CacheControl' => 'max-age=604800',

     * FFMPEG & FFProbe binaries path, only used if you try to generate video
     * thumbnails and have installed the php-ffmpeg/php-ffmpeg composer
     * dependency.
    'ffmpeg_binaries' => '/usr/bin/ffmpeg',
    'ffprobe_binaries' => '/usr/bin/ffprobe',

And finally you should add a disk to app/config/filesystems.php. This would be a typical configuration:

    'disks' => [

        'media' => [
            'driver' => 'local',
            'root'   => public_path().'/media',

All files of the medialibrary will be stored on that disk. If you are planning on working with the image manipulations you should configure a queue on your service with the name specified in the config file.

Lumen Support

Lumen configuration is slightly more involved but features and API are identical to Laravel.

Install using this command:

composer require spatie/laravel-medialibrary

Uncomment the following lines in the bootstrap file:

// bootstrap/app.php:

Configure the laravel-medialibrary service provider (and AppServiceProvider if not already enabled):

// bootstrap/app.php:

Update the AppServiceProvider register method to bind the filesystem manager to the IOC container:

// app/Providers/AppServiceProvider.php
public function register()
    $this->app->singleton('filesystem', function ($app) {
        return $app->loadComponent('filesystems', 'Illuminate\Filesystem\FilesystemServiceProvider', 'filesystem');

    $this->app->bind('Illuminate\Contracts\Filesystem\Factory', function($app) {
        return new \Illuminate\Filesystem\FilesystemManager($app);

Manually copy the package config file to app\config\laravel-medialibrary.php (you may need to create the config directory if it does not already exist).

Copy the Laravel filesystem config file into app\config\filesystem.php. You should add a disk configuration to the filesystem config matching the defaultFilesystem specified in the laravel-medialibrary config file.

Finally, update boostrap/app.php to load both config files:

// bootstrap/app.php


You can run the tests with:



Please see UPGRADING for details.


Please see CONTRIBUTING for details.


If you discover any security related issues, please email instead of using the issue tracker.


A big thank you to Nicolas Beauvais for helping out with the issues on this repo.


About Spatie

Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.


The MIT License (MIT). Please see License File for more information.