Thumbnails

🖼️

Creating thumbnails with Thumbnail and the Twig function thumbnail().

Thumbnail

Class that creates, converts and cleans thumbnails. It is configured by the constructor with imagony.thumbnails, the other methods are static, so they can be called without an instance after the service was created.

public function __construct(array $parameters, ?LoggerInterface $logger = null, bool $debug = false)

• $parameters: configuration imagony.thumbnails.
• $logger: receives warnings about problems which do not stop the page. Warnings about the installation are logged only once.
• $debug: unsupported formats throw an exception in debug mode, see the strict option.

create

Thumbnail::create(string $path, ?string $filename = null, ?int $width = null, ?int $height = null, array $flags = [], ?int $quality = null, array $formats = []): string

Returns the URL path of the thumbnail, relative to base and starting with /, e.g. /thumbnails/blog/image_x250f1q80mt1700000000.jpg.

• $path is a name of a template or a folder relative to base. For a template, its path, width, height, flags and quality are used and the other arguments are ignored.
• Empty $flags use the default flags, empty $formats use the default formats.
• Without $width and $height the source image itself is returned, nothing is generated.
• A missing or unreadable source gives the fallback image. With the built-in placeholder the URL is /_imagony/no-image.png.
• A source image which can not be processed is logged as a warning, a missing one is not. SVG files are returned as they are.
• Formats are created next to the thumbnail as <thumbnail>.webp / <thumbnail>.avif. A format PHP can not write throws an exception when strict is on, otherwise it is skipped and logged once.
• Throws \RuntimeException if folder does not exist and can not be created.

Thumbnails are cached: the file name contains the size, flags, quality and the modification time of the source (<name>_<width>x<height>f<flags>q<quality>mt<mtime>.<ext>), so a changed source gets a new thumbnail. Thumbnails of a template are stored in folder/<template>/, of a direct path in folder/<last folder name>/.

Usage:

use Imagony\Thumbnails\Thumbnail;

// template
Thumbnail::create("blog", "image.jpg");

// direct path
Thumbnail::create("images/gallery/", "image.jpg", 800, 600);

// with flags, quality and formats
Thumbnail::create("images/gallery/", "image.jpg", 400, 400, ["exact"], 85, ["webp", "avif"]);

generate

Thumbnail::generate(): void creates thumbnails of all files (not in subfolders) in the folders of all templates, including the configured formats.

clean

Thumbnail::clean(bool $dryRun = false): array removes files from folder, including subfolders of templates. Source images, folders and dot files (e.g. .gitkeep) are kept. Returns paths of the removed files (of the found ones for a dry run).

Throws \LogicException if folder is, or contains, base or the folder of any template, because the source images would be removed.

getParameters

Thumbnail::getParameters(): array returns the configuration passed to the constructor.

getPath

Thumbnail::getPath(string $path): string returns the path of the template when $path is a template name, otherwise $path unchanged.

Twig function

ImagonyExtension adds the function thumbnail() which accepts the same arguments as Thumbnail::create().

{# template #}
<img src="{{ thumbnail('blog', 'image.jpg') }}" alt="Blog image">

{# direct path with named arguments #}
<img src="{{ thumbnail('images/gallery/', item.image, width: 800, height: 600) }}" alt="">

With <picture>

The formats are created next to the thumbnail, so append the extension to its URL. Add formats: ['webp', 'avif'] to the configuration first.

<picture>
    <source srcset="{{ thumbnail('blog', 'image.jpg') }}.avif" type="image/avif">
    <source srcset="{{ thumbnail('blog', 'image.jpg') }}.webp" type="image/webp">
    <img src="{{ thumbnail('blog', 'image.jpg') }}" alt="Blog image">
</picture>

Parameter classes

Thumbnails and Template in Imagony\Thumbnails\Parameters are plain classes describing the structure of the configuration (base, folder, fallback, flags, formats and path, width, height, flags, quality).