Skip navigation
Scope

Enter at least two characters.
Searching…
No matching documentation found.
Search is temporarily unavailable.

ThumbHash Changelog

Release notes for ThumbHash.

3.0.0

🏎️ Performance

  • Image samples are now created in memory without writing thumbnails to the media folder
  • The built-in ThumbHash codec replaces srwiez/thumbhash

Uncached placeholder creation, 2.1.1 vs 3.0.0 (PHP 8.5, ImageMagick 7.1, libgd 2.3):

Image Engine 2.1.1 3.0.0 Speedup
Starterkit images, average of 56 GD 17.9 ms 8.6 ms 2.1×
Starterkit images, average of 56 Imagick 21.6 ms 6.0 ms 3.6×
933 × 1400 JPEG GD 19.8 ms 10.0 ms 2.0×
933 × 1400 JPEG Imagick 24.5 ms 8.4 ms 3.0×
6000 × 4000 JPEG GD 248 ms 92 ms 2.7×
6000 × 4000 JPEG Imagick 255 ms 46 ms 5.5×

ThumbHash codec alone, srwiez/thumbhash (used by 2.x) vs 3.0.0:

Operation srwiez/thumbhash 3.0.0 Speedup
Encode a 32 × 21 sample (default size) 173 µs 82 µs 2.1×
Encode a 100 × 67 sample 1448 µs 610 µs 2.4×
Encode a 24 × 32 sample with alpha 237 µs 152 µs 1.6×
Decode to a PNG data URI 544–681 µs 152–179 µs 3.6–3.8×

🚨 Breaking changes

  • New placeholders have different hashes; cached 2.x hashes remain valid, or flush tobimori.thumbhash.encode to regenerate them
  • Deprecated option arrays were removed; use thumbhash(16/9) and thumbhashUri(16/9, 2)
  • engine now defaults to Imagick when available and GD otherwise; set it to gd to keep GD
  • sampleMaxSize now defaults to 32 and is capped at 100

🐛 Bug fixes

  • Images near the sampleMaxSize limit no longer throw an uncaught exception #12
  • Rare PHP 8.3 round() edge cases no longer produce different hashes
  • Imagick now reads only the first animation frame and converts CMYK images to sRGB

Full Changelog: https://github.com/tobimori/kirby-thumbhash/compare/2.1.1...3.0.0

2.1.1

🐛 Bug fixes

  • Fix source files being deleted if thumb generation failed or is unsupported (#10)

2.1.0

🎉 Features

  • Add hasTransparency() file/asset method — detect if an image has transparent pixels via the thumbhash decode cache

2.0.2

🐛 Bug fixes

  • Fix implicit float-to-int conversion when using ratio as cache array key

2.0.1

🐛 Bug fixes

  • Fix imagedestroy() deprecation warning on PHP 8.5
  • Fix encoding with custom ratio returning cached result from first ratio (#9)

2.0.0

Breaking Changes

  • Requires PHP 8.3+ (was 8.2+)
  • Requires Kirby 5.0+ (was 4.0+)

All existing code continues to work.

What's New

  • Average color extraction: averageColor() and averageColorRgba()
  • Image processing drivers: GD (default) or Imagick
  • Cleaner parameter syntax (old array syntax still supported)
  • Better error handling in debug mode

New Syntax

// New
$file->thumbhash(16/9);
$file->thumbhashUri(16/9, 2);
$file->averageColor('rgb', 16/9);

// Old (still works, will be removed in v3.0)
$file->thumbhash(['ratio' => 16/9]);
$file->thumbhashUri(['ratio' => 16/9, 'blurRadius' => 2]);

New Methods

$file->averageColor();        // '#FF8800AA'
$file->averageColor('rgb');   // 'rgb(255 136 0 / 0.67)'
$file->averageColor('rgba');  // 'rgba(255, 136, 0, 0.67)'
$file->averageColorRgba();    // ['r' => 255, 'g' => 136, 'b' => 0, 'a' => 0.67]

Optional: Use Imagick Driver

pecl install imagick

// config.php
return [
    'tobimori.thumbhash.engine' => 'imagick',
];

Full Changelog: https://github.com/tobimori/kirby-thumbhash/compare/1.1.1...2.0.0

1.1.1

Full Changelog: https://github.com/tobimori/kirby-thumbhash/compare/1.1.0...1.1.1

1.1.0

This release enables the encode & decode file caching by default and should significantly speed up your site.

Full Changelog: https://github.com/tobimori/kirby-thumbhash/compare/1.0.0...1.1.0

1.0.0

Initial release