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.
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
You can register as many media conversions as you want
// in your modeluseSpatie\Image\Manipulations;// ...publicfunctionregisterMediaConversions(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 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
By default a conversion will be performed on all files regardless of which collection 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 modelpublicfunctionregisterMediaConversions(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 ''
By default, a conversion will be added to the connection and queue that you've specified in the configuration. If you want your image to be created directly (and not on a queue) use nonQueued on a conversion.
// in your modelpublicfunctionregisterMediaConversions(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 modelpublicfunctionregisterMediaConversions(Media $media =null):void{$this->addMediaConversion('thumb')->width(368)->height(232)->queued();}
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 modelpublic $registerMediaConversionsUsingModelInstance =true;publicfunctionregisterMediaConversions(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.