[5.x] Custom asset thumbnails

[daun]

Allow the registration of custom asset thumbnail generators for exotic file types like videos, PDFs, and 3D objects.

Moves the creation of thumbnail urls from the Asset model to a ThumbnailService, which in turn delegates to a set of ThumbnailGenerators. Users and addons can now create custom thumbnail providers for different file types. This PR does not add any new thumbnail generators, it just opens it up for extension.

Example

These examples use short animated Cloudflare Stream thumbnail urls for videos. Vimeo and Mux offer similar endpoints for animated image versions of uploaded videos.

List

Editor

Generators

Generators have two methods, one to advertise support for a file format, one for generating the thumbnail url.

namespace App\ThumbnailGenerators;

use Statamic\Contracts\Assets\Asset;
use Statamic\Contracts\Assets\ThumbnailGenerator;

class CloudflareStream implements ThumbnailGenerator
{
    public function accepts(Asset $asset): bool {
        return $asset->extension() === 'mp4';
    }

    public function generate(Asset $asset, mixed $params): ?string {
        return 'https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.gif?time=1s&height=200&duration=4s';
    }
}

Generators can be registered from a new config option in config/statamic/cp.php:

return [

    /*
    |--------------------------------------------------------------------------
    | Thumbnail Generators
    |--------------------------------------------------------------------------
    |
    | Statamic will generate thumbnails for most image types. If you wish to
    | generate thumbnails for other file types like videos or PDFs, you may
    | register custom thumbnail generators here.
    |
    */

    'thumbnail_generators' => [
        \App\Thumbnails\Generators\Vimeo::class,
        \App\Thumbnails\Generators\Pdf::class,
    ],

];

Notes

• Not sure about the naming — thumbnail generator? thumbnail provider? thumbnail service?
• I purposely didn't move the code into the Imaging namespace since not all thumbnails need to come from images — think font files, audio visualizations, 3D objects.

Closes

Closes statamic/ideas#1120

[jasonvarga]

This is awesome.

What do you think should happen if there are multiple generators registered that accept the same type? How do you determine which one takes precedence?

[daun]

@jasonvarga It's currently reverse-sorted to choose the last matching generator that is registered, prioritizing custom generators over built-in generators. There is no manual override at this point. I was at some point thinking about adding a priority flag, but figured it can also be added if and when a need arises. Do you think it makes sense to include one right away?

[jasonvarga]

I was thinking it should rather be a configuration option.

For instance, I could see someone installing multiple addons that could provide generators for the same file type.

You can leave it with us to think on a bit more though.

[daun]

@jasonvarga Makes sense! We could also require people register them manually from config/statamic/assets.php. In that case, the order becomes the priority in case of overlap:

return [

    /*
    |--------------------------------------------------------------------------
    | Thumbnail Generators
    |--------------------------------------------------------------------------
    |
    | Register custom thumbnail generators for exotic file types.
    |
    */

    'thumbnail_generators' => [
        \App\Thumbnails\Pdf::class,
        \Some\Addon\Thumbnails\Video::class,
        \Another\Addon\Thumbnails\WebmVideo::class
    ],

];

[daun]

I've given the config option a try. With that, it's possible (and required) to manually register any custom thumbnail generators. Feels like a good ergonomic way of registering them and handling precedence. Without self-registering generators, the code becomes a bit simpler too :)

// config/statamic/cp.php

return [

    /*
    |--------------------------------------------------------------------------
    | Thumbnail Generators
    |--------------------------------------------------------------------------
    |
    | Statamic will generate thumbnails for most image types. If you wish to
    | generate thumbnails for other file types like videos or PDFs, you may
    | register custom thumbnail generators here.
    |
    */

    'thumbnail_generators' => [
        \App\Thumbnails\Generators\Vimeo::class,
        \App\Thumbnails\Generators\Pdf::class,
    ],

];

[jasonvarga]

This is awesome. But I'm going to close it for now and make it a note to bring it into #10204 in some fashion.

[daun]

@jasonvarga Makes sense! Part of what I was trying to do is open up the control panel to previewing all kinds of exotic file formats, not just images. So it'd only be tangentially related to image manipulation in the case of e.g. PDF files or 3D models. It'd be awesome if you could keep that use case in mind when factoring something like it back into the new driver based image functionality — it would really make Statamic shine for media-based publishing workflows that aren't currently possible anywhere else :)

[jasonvarga]

💯 I understand your vision and love it. Will definitely keep it in mind.