Darkroom

Thumbnails for PHP, built with Kirby CMS in mind but ready for any project. Darkroom resizes, crops, orients and converts images with GD, ImageMagick or libvips, and all three make the same thumb.

$darkroom = new Darkroom\Darkroom();
$darkroom->process('photo.jpg', 'thumbs/photo.webp', ['width' => 800]);

• Formats: JPEG, PNG, GIF, WebP, AVIF, HEIC, JPEG XL and JPEG 2000, as long as the driver supports them
• Quality: one perceptual scale, the same look in every format
• Color: color profiles kept, CMYK converted to sRGB, HDR tone-mapped
• Orientation: EXIF, HEIF and JPEG XL orientation applied to the pixels
• Animation: frames of GIF, WebP and JPEG XL kept where the driver can
• Safety: a pixel limit before decoding, resource limits, atomic writes

composer require getkirby/darkroom

PHP 8.4 or newer and one of the drivers.

use Darkroom\Darkroom;

$darkroom = new Darkroom();
$source   = $darkroom->open('photo.jpg');
$plan     = $darkroom->plan($source, ['width' => 400, 'height' => 300, 'crop' => true]);

// size, format and name are known before any pixel is decoded
$width = $plan->width();
$file  = 'thumbs/photo-' . $plan->key() . '.' . $plan->format->extension();

$darkroom->process($plan, $file);

Options::from($plan->key()) reads a key back, so a thumb can be made later from its file name alone.

Thumbs are never enlarged, not even by a crop: it is exactly width × height, or the largest part of that ratio a smaller source has. A crop with one side is a square.

quality is a SSIMULACRA2 score: how close the thumb stays to its source, on one scale for every format. An average observer at 1:1 notices the distortion:

Each driver turns the score into its encoder's quality and chroma subsampling, so that the median CID22 validation image reaches it.

$darkroom = new Darkroom(
	drivers:  ['vips', 'imagick'],
	defaults: ['quality' => 80, 'format' => 'webp'],
	settings: ['limit' => 50_000_000],
);

drivers takes aliases, class names or Darkroom\Driver instances, by default ['imagick', 'gd', 'vips']. Each thumb goes to the first available one that reads the source and writes the format. One that can't animate the format writes the first frame.

1. Read: open() reads the header only: format, size, orientation, color profile.
2. Plan: the size is fitted, the crop placed, format and encoder settings chosen.
3. Decode: JPEGs at a reduced size where the driver can (ImageMagick, libvips).
4. Process: crop, resize, convert to sRGB where needed, orient, filter.
5. Encode: without metadata but the color profile; JPEG flattened on white.
6. Write: to a temporary file, renamed once complete.

Darkroom won't do SVG, PDF, video, image editing (text, watermarks, shapes, color extraction), caching, URLs or job files.

See CONTRIBUTING.md.

MIT