Defining conversions | laravel-medialibrary | Spatie SPATIE Laravel Media Library ======================== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-medialibrary](https://spatie.be/docs/laravel-medialibrary/v9) Converting-images Defining conversions 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/v9/introduction) - [ Support us ](https://spatie.be/docs/laravel-medialibrary/v9/support-us) - [ Base installation ](https://spatie.be/docs/laravel-medialibrary/v9/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v9/questions-issues) - [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v9/requirements) - [ Upgrading ](https://spatie.be/docs/laravel-medialibrary/v9/upgrading) - [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v9/changelog) - [ Troubleshooting ](https://spatie.be/docs/laravel-medialibrary/v9/troubleshooting) - [ About us ](https://spatie.be/docs/laravel-medialibrary/v9/about-us) Basic usage ----------- - [ Preparing your model ](https://spatie.be/docs/laravel-medialibrary/v9/basic-usage/preparing-your-model) - [ Associating files ](https://spatie.be/docs/laravel-medialibrary/v9/basic-usage/associating-files) - [ Retrieving media ](https://spatie.be/docs/laravel-medialibrary/v9/basic-usage/retrieving-media) Working with media collections ------------------------------ - [ Simple media collections ](https://spatie.be/docs/laravel-medialibrary/v9/working-with-media-collections/simple-media-collections) - [ Defining media collections ](https://spatie.be/docs/laravel-medialibrary/v9/working-with-media-collections/defining-media-collections) Converting images ----------------- - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v9/converting-images/defining-conversions) - [ Retrieving converted images ](https://spatie.be/docs/laravel-medialibrary/v9/converting-images/retrieving-converted-images) - [ Optimizing converted images ](https://spatie.be/docs/laravel-medialibrary/v9/converting-images/optimizing-converted-images) - [ Regenerating images ](https://spatie.be/docs/laravel-medialibrary/v9/converting-images/regenerating-images) Handling uploads with Media Library Pro --------------------------------------- - [ Introduction ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/introduction) - [ Installation ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/installation) - [ Processing uploads on the server ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/processing-uploads-on-the-server) - [ Handling uploads with Blade ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/handling-uploads-with-blade) - [ Handling uploads with Livewire ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/handling-uploads-with-livewire) - [ Handling uploads with Vue ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/handling-uploads-with-vue) - [ Handling uploads with React ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/handling-uploads-with-react) - [ Creating custom Vue components ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/creating-custom-vue-components) - [ Creating custom React components ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/creating-custom-react-components) - [ Customizing CSS ](https://spatie.be/docs/laravel-medialibrary/v9/handling-uploads-with-media-library-pro/customizing-css) Responsive images ----------------- - [ Getting started with responsive images ](https://spatie.be/docs/laravel-medialibrary/v9/responsive-images/getting-started-with-responsive-images) - [ Using your own width calculator ](https://spatie.be/docs/laravel-medialibrary/v9/responsive-images/using-your-own-width-calculator) - [ Customizing the rendered html ](https://spatie.be/docs/laravel-medialibrary/v9/responsive-images/customizing-the-rendered-html) - [ Generating your own tiny placeholder ](https://spatie.be/docs/laravel-medialibrary/v9/responsive-images/generating-your-own-tiny-placeholder) - [ Responsive images demo ](https://spatie.be/docs/laravel-medialibrary/v9/responsive-images/demo) Converting other file types --------------------------- - [ Using image generators ](https://spatie.be/docs/laravel-medialibrary/v9/converting-other-file-types/using-image-generators) - [ Creating a custom image generator ](https://spatie.be/docs/laravel-medialibrary/v9/converting-other-file-types/creating-a-custom-image-generator) Downloading media ----------------- - [ Downloading a single file ](https://spatie.be/docs/laravel-medialibrary/v9/downloading-media/downloading-a-single-file) - [ Downloading multiple files ](https://spatie.be/docs/laravel-medialibrary/v9/downloading-media/downloading-multiple-files) Advanced usage -------------- - [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/working-with-multiple-filesystems) - [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/using-custom-properties) - [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/storing-media-specific-manipulations) - [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/using-your-own-model) - [ Outputting media ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/outputting-media) - [ Rendering media ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/rendering-media) - [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/using-a-custom-directory-structure) - [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/ordering-media) - [ Using a custom media downloader ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/using-a-custom-media-downloader) - [ Moving media ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/moving-media) - [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/consuming-events) - [ Generating custom urls ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/generating-custom-urls) - [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/overriding-the-default-filesystem-behaviour) - [ Naming generated files ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/naming-files) - [ Disable CDN ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/disable-cdn) - [ Customising Database Connections ](https://spatie.be/docs/laravel-medialibrary/v9/advanced-usage/customising-database-connections) API --- - [ Adding files ](https://spatie.be/docs/laravel-medialibrary/v9/api/adding-files) - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v9/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 ` Defining conversions ==================== ### On this page 1. [ Are you a visual learner? ](#content-are-you-a-visual-learner) 2. [ A single conversion ](#content-a-single-conversion) 3. [ Using multiple conversions ](#content-using-multiple-conversions) 4. [ Performing conversions on specific collections ](#content-performing-conversions-on-specific-collections) 5. [ Queuing conversions ](#content-queuing-conversions) 6. [ Using model properties in a conversion ](#content-using-model-properties-in-a-conversion) When adding files to the media library it can automatically create derived versions such as thumbnails and banners. Media conversions will be executed whenever a `jpg`, `png`, `svg`, `webp`, `pdf`, `mp4 `, `mov` or `webm` file is added to the media library. By default, the conversions will be saved as a `jpg` files. This can be overwritten using the `format()` or `keepOriginalImageFormat()` methods. Internally, [spatie/image](https://docs.spatie.be/image/v1/) is used to manipulate the images. You can use [any manipulation function](https://docs.spatie.be/image) from that package. Are you a visual learner? --------------------------------------------------------------------------------------------------------------------------------- Here's a video that shows how to working with conversion. Want to see more videos like this? Check out our [free video course on how to use Laravel Media Library](https://spatie.be/videos/discovering-laravel-media-library). A single conversion ----------------------------------------------------------------------------------------------------------------- You should add a method called `registerMediaConversions` to your model. In that model you can define the media conversion. Here's an example: ``` use Illuminate\Database\Eloquent\Model; use Spatie\MediaLibrary\MediaCollections\Models\Media; use Spatie\MediaLibrary\HasMedia; use Spatie\MediaLibrary\InteractsWithMedia; class YourModel extends Model implements HasMedia { use InteractsWithMedia; public function registerMediaConversions(Media $media = null): void { $this->addMediaConversion('thumb') ->width(368) ->height(232) ->sharpen(10); } } ``` Let's add an image to the media library. ``` $media = YourModel::first()->addMedia($pathToImage)->toMediaCollection(); ``` Besides storing the original item, the media library also has created a derived image. ``` $media->getPath(); // the path to the where the original image is stored $media->getPath('thumb'); // the path to the converted image with dimensions 368x232 $media->getUrl(); // the url to the where the original image is stored $media->getUrl('thumb'); // the url to the converted image with dimensions 368x232 ``` Using multiple conversions -------------------------------------------------------------------------------------------------------------------------------------- You can register as many media conversions as you want ``` // in your model use Spatie\Image\Manipulations; // ... public function registerMediaConversions(Media $media = null): void { $this->addMediaConversion('thumb') ->width(368) ->height(232) ->sharpen(10); $this->addMediaConversion('old-picture') ->sepia() ->border(10, 'black', Manipulations::BORDER_OVERLAY); $this->addMediaConversion('thumb-cropped') ->crop('crop-center', 400, 400); // Trim or crop the image to the center for sepecified width and height. } ``` Use the conversions like this: ``` $media->getUrl('thumb') // the url to the thumbnail $media->getUrl('old-picture') // the url to the sepia, bordered version ``` Performing conversions on specific collections -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- By default a conversion will be performed on all files regardless of which [collection](/laravel-medialibrary/v9/working-with-media-collections/simple-media-collections) is used. Conversions can also be performed on all specific collections by adding a call to `performOnCollections`. This is how that looks like in the model: ``` // in your model public function registerMediaConversions(Media $media = null): void { $this->addMediaConversion('thumb') ->width(368) ->height(232) ->performOnCollections('images', 'downloads'); } ``` ``` // a thumbnail will be generated for this media item $media = $yourModel->addMedia($pathToImage)->toMediaCollection('images'); $media->getUrl('thumb') // the url to the thumbnail //but not for this one $media = $yourModel->addMedia($pathToImage)->toMediaCollection('other collection'); $media->getUrl('thumb') // returns '' ``` Queuing conversions ----------------------------------------------------------------------------------------------------------------- By default, a conversion will be added to the queue that you've [specified in the configuration](https://docs.spatie.be/laravel-medialibrary/v9/installation-setup). If you want your image to be created directly (and not on a queue) use `nonQueued` on a conversion. ``` // in your model public function registerMediaConversions(Media $media = null): void { $this->addMediaConversion('thumb') ->width(368) ->height(232) ->nonQueued(); } ``` If you have set `queue_conversions_by_default` in the `media-library` config file to `false`, all conversions will all be generated synchronously. If you want to generate a conversion on a queue, while `queue_conversions_by_default` is set to `false`, use the `queued` method. ``` // in your model public function registerMediaConversions(Media $media = null): void { $this->addMediaConversion('thumb') ->width(368) ->height(232) ->queued(); } ``` Using model properties in a conversion -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- When registering conversions inside the `registerMediaConversions` function you won't have access to your model properties by default. If you want to use a property of your model as input for defining a conversion you must set `registerMediaConversionsUsingModelInstance` to ` true` on your model. ``` // in your model public $registerMediaConversionsUsingModelInstance = true; public function registerMediaConversions(Media $media = null): void { $this->addMediaConversion('thumb') ->width($this->width) ->height($this->height) ->performOnCollections('images', 'downloads'); } ``` Be aware that this can lead to a hit in performance. When processing media the media library has to perform queries to fetch each separate model.