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/v11) 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) Defining conversions - [ Introduction ](https://spatie.be/docs/laravel-medialibrary/v11/introduction) - [ Support us ](https://spatie.be/docs/laravel-medialibrary/v11/support-us) - [ Base installation ](https://spatie.be/docs/laravel-medialibrary/v11/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v11/questions-issues) - [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v11/requirements) - [ Upgrading ](https://spatie.be/docs/laravel-medialibrary/v11/upgrading) - [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v11/changelog) - [ Troubleshooting ](https://spatie.be/docs/laravel-medialibrary/v11/troubleshooting) - [ About us ](https://spatie.be/docs/laravel-medialibrary/v11/about-us) Basic usage ----------- - [ Preparing your model ](https://spatie.be/docs/laravel-medialibrary/v11/basic-usage/preparing-your-model) - [ Associating files ](https://spatie.be/docs/laravel-medialibrary/v11/basic-usage/associating-files) - [ Retrieving media ](https://spatie.be/docs/laravel-medialibrary/v11/basic-usage/retrieving-media) Working with media collections ------------------------------ - [ Simple media collections ](https://spatie.be/docs/laravel-medialibrary/v11/working-with-media-collections/simple-media-collections) - [ Defining media collections ](https://spatie.be/docs/laravel-medialibrary/v11/working-with-media-collections/defining-media-collections) Converting images ----------------- - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v11/converting-images/defining-conversions) - [ Retrieving converted images ](https://spatie.be/docs/laravel-medialibrary/v11/converting-images/retrieving-converted-images) - [ Optimizing converted images ](https://spatie.be/docs/laravel-medialibrary/v11/converting-images/optimizing-converted-images) - [ Regenerating images ](https://spatie.be/docs/laravel-medialibrary/v11/converting-images/regenerating-images) Responsive images ----------------- - [ Getting started with responsive images ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/getting-started-with-responsive-images) - [ Using your own width calculator ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/using-your-own-width-calculator) - [ Customizing the rendered HTML ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/customizing-the-rendered-html) - [ Generating your own tiny placeholder ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/generating-your-own-tiny-placeholder) - [ Responsive images demo ](https://spatie.be/docs/laravel-medialibrary/v11/responsive-images/demo) Converting other file types --------------------------- - [ Using image generators ](https://spatie.be/docs/laravel-medialibrary/v11/converting-other-file-types/using-image-generators) - [ Creating a custom image generator ](https://spatie.be/docs/laravel-medialibrary/v11/converting-other-file-types/creating-a-custom-image-generator) Downloading media ----------------- - [ Downloading a single file ](https://spatie.be/docs/laravel-medialibrary/v11/downloading-media/downloading-a-single-file) - [ Downloading multiple files ](https://spatie.be/docs/laravel-medialibrary/v11/downloading-media/downloading-multiple-files) Advanced usage -------------- - [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/working-with-multiple-filesystems) - [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-custom-properties) - [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/storing-media-specific-manipulations) - [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-your-own-model) - [ Outputting media ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/outputting-media) - [ Rendering media ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/rendering-media) - [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-a-custom-directory-structure) - [ Using a custom file removal strategy ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-a-custom-file-removal-strategy) - [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/ordering-media) - [ Using a custom media downloader ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/using-a-custom-media-downloader) - [ Moving media ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/moving-media) - [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/consuming-events) - [ Attaching media in mails ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/attaching-media-in-mails) - [ Generating custom URLs ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/generating-custom-urls) - [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/overriding-the-default-filesystem-behaviour) - [ Naming generated files ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/naming-files) - [ Disable CDN ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/disable-cdn) - [ Customising Database Connections ](https://spatie.be/docs/laravel-medialibrary/v11/advanced-usage/customising-database-connections) API --- - [ Adding files ](https://spatie.be/docs/laravel-medialibrary/v11/api/adding-files) - [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v11/api/defining-conversions) 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. [ Using a specific disk ](#content-using-a-specific-disk) 6. [ Queuing conversions ](#content-queuing-conversions) 7. [ Deferred conversions ](#content-deferred-conversions) 8. [ 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`, `avif`, `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://spatie.be/docs/image/v3) is used to manipulate the images. You can use [any manipulation function](https://spatie.be/docs/image) from that package. Please check [the image generator docs](/docs/laravel-medialibrary/v11/converting-other-file-types/using-image-generators) for additional installation requirements when working with PDF, SVG or video formats. Are you a visual learner? --------------------------------------------------------------------------------------------------------------------------------- Here's a video that shows how to work with conversions. Want to see more videos like this? Check out our [free video course on how to use Laravel Media Library](https://spatie.be/courses/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 where the original image is stored $media->getPath('thumb'); // the path to the converted image with dimensions 368x232 $media->getUrl(); // the url to 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\Enums\BorderType; use Spatie\Image\Enums\CropPosition; // ... public function registerMediaConversions(?Media $media = null): void { $this->addMediaConversion('thumb') ->width(368) ->height(232) ->sharpen(10); $this->addMediaConversion('old-picture') ->sepia() ->border(10, BorderType::Overlay, 'black'); $this->addMediaConversion('thumb-cropped') ->crop(400, 400, CropPosition::Center); // Trim or crop the image to the center for specified 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](/docs/laravel-medialibrary/v11/working-with-media-collections/simple-media-collections) is used. Conversions can also be performed on 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') ->performOnCollections('images', 'downloads') ->width(368) ->height(232); } ``` ``` // 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 '' ``` Using a specific disk ----------------------------------------------------------------------------------------------------------------------- You can ensure that conversions added to a collection are automatically added to a certain disk. ``` public function registerMediaCollections(): void { $this ->addMediaCollection('big-files') ->useDisk('s3') ->storeConversionsOnDisk('public'); } ``` Queuing conversions ----------------------------------------------------------------------------------------------------------------- By default, a conversion will be added to the connection and queue that you've [specified in the configuration](/docs/laravel-medialibrary/v11/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(); } ``` The default behaviour is that queued conversions will run **after all database transactions have been committed**. This prevents unexpected behaviour where the model does not yet exist in the database and the conversion is disregarded. If you need the conversions to run within your transaction, you can set the `queue_conversions_after_database_commit`in the `media-library` config file to `false`. Deferred conversions -------------------------------------------------------------------------------------------------------------------- Instead of processing a conversion synchronously or dispatching it to a queue, you can use `deferred()` to schedule the conversion to run after the HTTP response has been sent to the browser. This uses Laravel's [`defer()` helper](https://laravel.com/docs/13.x/helpers#deferred-functions) under the hood. Deferred conversions are useful when you need a conversion to happen promptly after upload without blocking the upload request itself. A common case is generating an avatar thumbnail that should be available quickly, but doesn't need to delay the response. ``` // in your model public function registerMediaConversions(?Media $media = null): void { $this->addMediaConversion('thumb') ->width(368) ->height(232) ->deferred(); } ``` Deferred conversions run inline in the same PHP process after the response is flushed, so they keep the worker busy until they finish. For slow conversions, or models with many conversions, prefer `queued()` so the work runs on a queue worker instead. Deferred conversions require Laravel 11.23 or higher (the version that introduced the `defer()` helper). On older versions, use `queued()` or `nonQueued()`. 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') ->performOnCollections('images', 'downloads') ->width($this->width) ->height($this->height); } ``` 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. A good match? ------------- ### What we do best - All things Laravel - Custom frontend components - Building APIs - AI-powered features - Simplifying things - Clean solutions - Integrating services ### Not our cup of tea - WordPress themes - Cutting corners - Free mockups to win a job - "Just execute the briefing" In short: we'd like to be a **substantial part** of your project. [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)