Defining conversions

When adding files to the medialibrary it can automatically created derived versions such a thumbnails and banners.

If you want to use this functionality your models should implement the HasMediaConversions interface instead of HasMedia. This interface expects an implementation of the registerMediaConversions method.

Media conversions will be executed whenever a jpg, png, svg, pdf, mp4 , mov or webm file is added to the medialibrary. By default, the conversions will be saved as a jpg files. This can be overwritten using the format() or keepOriginalImageFormat() methods.

Internally, spatie/image is used to manipulate the images. You can use any manipulation function from that package.

##A single conversion

Here's an example of how a model can implement this.

use Illuminate\Database\Eloquent\Model;
use Spatie\MediaLibrary\HasMedia\Interfaces\HasMediaConversions;
use Spatie\MediaLibrary\HasMedia\HasMediaTrait;

class NewsItem extends Model implements HasMediaConversions
{
    use HasMediaTrait;

    public function registerMediaConversions()
    {
        $this->addMediaConversion('thumb')
              ->width(368)
              ->height(232)
              ->sharpen(10)
              ->optimize();
    }
}

Let's add an image to the medialibrary.

$media = NewsItem::first()->addMedia($pathToImage)->toMediaCollection();

Besides storing the original item, the medialibrary 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

Because we used optimize in the registerMediaConversions method, the converted image will have been optimized by the underlying image-optimizer package.

##Using multiple conversions

You can register as many media conversions as you want

// in your model
use Spatie\Image\Manipulations;

    public function registerMediaConversions()
    {
        $this->addMediaConversion('thumb')
              ->width(368)
              ->height(232)
              ->sharpen;

        $this->addMediaConversion('old-picture')
              ->sepia()
              ->border(10, 'black', Manipulations::BORDER_OVERLAY);
    }

Use the conversions like this:

$media->getUrl('thumb') // the url to the thubmnail
$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 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()
    {
        $this->addMediaConversion('thumb')
              ->width(368)
              ->height(232)
              ->performOnCollections('images', 'downloads');
    }

// a thumbnail will be generated for this media item
$media = $newsItem->addMedia($pathToImage)->toMediaCollection('images');
$media->getUrl('thumb') // the url to the thubmnail

//but not for this one
$media = $newsItem->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. 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()
    {
        $this->addMediaConversion('thumb')
              ->width(368)
              ->height(232)
              ->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()
    {
        $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 medialibrary has to perform queries to fetch each separate model.