Installation & setup | laravel-medialibrary | Spatie SPATIE Laravel Media Library ======================== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-medialibrary](https://spatie.be/docs/laravel-medialibrary/v7) Installation & setup 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/v7/introduction) - [ Support us ](https://spatie.be/docs/laravel-medialibrary/v7/support-us) - [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v7/requirements) - [ Installation & setup ](https://spatie.be/docs/laravel-medialibrary/v7/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v7/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v7/changelog) - [ About us ](https://spatie.be/docs/laravel-medialibrary/v7/about-us) Basic usage ----------- - [ Preparing your model ](https://spatie.be/docs/laravel-medialibrary/v7/basic-usage/preparing-your-model) - [ Associating files ](https://spatie.be/docs/laravel-medialibrary/v7/basic-usage/associating-files) - [ Retrieving media ](https://spatie.be/docs/laravel-medialibrary/v7/basic-usage/retrieving-media) Working with media collections ------------------------------ - [ Simple media collections ](https://spatie.be/docs/laravel-medialibrary/v7/working-with-media-collections/simple-media-collections) - [ Defining media collections ](https://spatie.be/docs/laravel-medialibrary/v7/working-with-media-collections/defining-media-collections) Converting images ----------------- - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v7/converting-images/defining-conversions) - [ Retrieving converted images ](https://spatie.be/docs/laravel-medialibrary/v7/converting-images/retrieving-converted-images) - [ Optimizing converted images ](https://spatie.be/docs/laravel-medialibrary/v7/converting-images/optimizing-converted-images) - [ Regenerating images ](https://spatie.be/docs/laravel-medialibrary/v7/converting-images/regenerating-images) Responsive images ----------------- - [ Getting started with responsive images ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/getting-started-with-responsive-images) - [ Using your own width calculator ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/using-your-own-width-calculator) - [ Customizing the rendered html ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/customizing-the-rendered-html) - [ Generating your own tiny placeholder ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/generating-your-own-tiny-placeholder) - [ Responsive images demo ](https://spatie.be/docs/laravel-medialibrary/v7/responsive-images/demo) Downloading media ----------------- - [ Downloading a single file ](https://spatie.be/docs/laravel-medialibrary/v7/downloading-media/downloading-a-single-file) - [ Downloading multiple files ](https://spatie.be/docs/laravel-medialibrary/v7/downloading-media/downloading-multiple-files) Converting other file types --------------------------- - [ Using image generators ](https://spatie.be/docs/laravel-medialibrary/v7/converting-other-file-types/using-image-generators) - [ Creating a custom image generator ](https://spatie.be/docs/laravel-medialibrary/v7/converting-other-file-types/creating-a-custom-image-generator) Advanced usage -------------- - [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/working-with-multiple-filesystems) - [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/using-custom-properties) - [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/storing-media-specific-manipulations) - [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/using-your-own-model) - [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/using-a-custom-directory-structure) - [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/ordering-media) - [ Moving media ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/moving-media) - [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/consuming-events) - [ Generating custom urls ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/generating-custom-urls) - [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v7/advanced-usage/overriding-the-default-filesystem-behaviour) API --- - [ Adding files ](https://spatie.be/docs/laravel-medialibrary/v7/api/adding-files) - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v7/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 ` Installation & setup ======================== Medialibrary can be installed via composer: ``` composer require "spatie/laravel-medialibrary:^7.0.0" ``` The package will automatically register a service provider. You need to publish and run the migration: ``` php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations" php artisan migrate ``` Publishing the config file is optional: ``` php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="config" ``` This is the default content of the config file: ``` return [ /* * The filesystems on which to store added files and derived images by default. Choose * one or more of the filesystems you've configured in config/filesystems.php. */ 'disk_name' => 'public', /* * The maximum file size of an item in bytes. * Adding a larger file 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 that should be used. */ 'media_model' => Spatie\MediaLibrary\Models\Media::class, /* * The engine that should perform the image conversions. * Should be either `gd` or `imagick`. */ 'image_driver' => 'gd', /* * 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. */ 'url_generator' => null, /* * The class that contains the strategy for determining a media file's path. */ 'path_generator' => null, 's3' => [ /* * The domain that should be prepended when generating urls. */ 'domain' => 'https://xxxxxxx.s3.amazonaws.com', ], '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', ], ], /* * These generators will be used to create an image of media files. */ 'image_generators' => [ Spatie\MediaLibrary\ImageGenerators\FileTypes\Image::class, Spatie\MediaLibrary\ImageGenerators\FileTypes\Pdf::class, Spatie\MediaLibrary\ImageGenerators\FileTypes\Svg::class, Spatie\MediaLibrary\ImageGenerators\FileTypes\Video::class, ], /* * Medialibrary will try to optimize all converted images by removing * metadata and applying a little bit of compression. These are * the optimizers that will be used by default. */ 'image_optimizers' => [ Spatie\ImageOptimizer\Optimizers\Jpegoptim::class => [ '--strip-all', // this strips out all text information such as comments and EXIF data '--all-progressive', // this will make sure the resulting image is a progressive one ], Spatie\ImageOptimizer\Optimizers\Pngquant::class => [ '--force', // required parameter for this package ], Spatie\ImageOptimizer\Optimizers\Optipng::class => [ '-i0', // this will result in a non-interlaced, progressive scanned image '-o2', // this set the optimization level to two (multiple IDAT compression trials) '-quiet', // required parameter for this package ], Spatie\ImageOptimizer\Optimizers\Svgo::class => [ '--disable=cleanupIDs', // disabling because it is known to cause troubles ], Spatie\ImageOptimizer\Optimizers\Gifsicle::class => [ '-b', // required parameter for this package '-O3', // this produces the slowest but best results ], ], /* * The path where to store temporary files while performing image conversions. * If set to null, storage_path('medialibrary/temp') will be used. */ 'temporary_directory_path' => null, /* * FFMPEG & FFProbe binaries path, only used if you try to generate video * thumbnails and have installed the php-ffmpeg/php-ffmpeg composer * dependency. */ 'ffmpeg_path' => '/usr/bin/ffmpeg', 'ffprobe_path' => '/usr/bin/ffprobe', ]; ``` By default medialibrary will store its files on Laravel's `public` disk. If you want a dedicated disk you should add a disk to `config/filesystems.php`. This would be a typical configuration: ``` ... 'disks' => [ ... 'media' => [ 'driver' => 'local', 'root' => public_path('media'), ], ... ``` Don't forget to ignore the directory of your configured disk so the files won't end up in your git repo. If you are planning on working with image manipulations it's recommended to configure a queue on your server and specify it in the config file. Want to use S3? Then follow Laravel's instructions on [how to add the S3 Flysystem driver](https://laravel.com/docs/filesystem#configuration). ### Optimization tools Medialibrary will use these tools to [optimize converted images](https://docs.spatie.be/laravel-medialibrary/v7/converting-images/optimizing-converted-images) if they are present on your system: - [JpegOptim](http://freecode.com/projects/jpegoptim) - [Optipng](http://optipng.sourceforge.net/) - [Pngquant 2](https://pngquant.org/) - [SVGO](https://github.com/svg/svgo) - [Gifsicle](http://www.lcdf.org/gifsicle/) Here's how to install all the optimizers on Ubuntu: ``` sudo apt install jpegoptim optipng pngquant gifsicle npm install -g svgo ``` And here's how to install the binaries on MacOS (using [Homebrew](https://brew.sh/)): ``` brew install jpegoptim brew install optipng brew install pngquant brew install svgo brew install gifsicle ```