ThumborProvider

Generates Thumbor transformation URLs. Self-hosted, open-source image processing server.

use Timber\Chainsaw\Provider\Thumbor\ThumborProvider;
use Timber\Chainsaw\Signer\Algorithm;
use Timber\Chainsaw\Signer\HmacUrlSigner;

$provider = new ThumborProvider(
    host: 'http://localhost:8084',
    signer: new HmacUrlSigner(key: 'thumbor-secret', algorithm: Algorithm::Sha1), // optional
);

Output: {host}/{signature|unsafe}/{manualCrop}/{fitIn}/{w}x{h}/{align}/{smart}/filters:{filters}/{source}

Thumbor signing is HMAC-SHA1 by default (the libthumbor reference). Pass algorithm: Algorithm::Sha256 if your Thumbor instance is configured for it.

Manipulation support

Legend: ✅ = implemented in Chainsaw, ⚠️ = supported with caveats, 🟦 = available on the CDN, not exposed by Chainsaw, ❌ = not available on this CDN.

Resize & crop

Manipulation Chainsaw Availability
Width ✅ Free
Height ✅ Free
Scale ❌ No scale-by-factor primitive; use width()/height()
Cover ✅ Free (crop() alias; compass / smart anchors — focal() throws, Thumbor needs a rectangle not a point)
ManualCrop ✅ Free
Contain ✅ Free
Pad ✅ Free
Stretch ✅ Free (via stretch() filter)
CropToRatio ❌ No aspect-ratio-only crop; use cover() with absolute dims
PadToRatio ❌ No aspect-ratio-only pad; use pad() with absolute dims
Proportion 🟦 Free (scale by percentage)
Smart crop 🟦 Free (content-aware/face detection)
Trim ✅ Free
Extract focal points 🟦 Free (return focal point data)

Filters & effects

Manipulation Chainsaw Availability
Blur ✅ Free
Sharpen ✅ Free
Brightness ✅ Free
Contrast ✅ Free
Gamma ❌
Greyscale ✅ Free
Sepia ❌
Pixelate ❌
Saturation ✅ Free
Hue ❌
Negate ❌
Equalize 🟦 Free (histogram equalization)
Noise 🟦 Free
Convolution 🟦 Free (custom kernel)
RGB channels 🟦 Free (per-channel adjustment)
Red-eye removal 🟦 Free

Decoration & orientation

Manipulation Chainsaw Availability
Background ✅ Free
Border ❌ Not available — no canvas-expanding border primitive
Flip ✅ Free
Rotate ⚠️ Free; 90/180/270 only — arbitrary angles throw UnsupportedManipulator
AutoOrient ✅ Free; no-op at URL level (EXIF auto-orient is controlled server-side via RESPECT_ORIENTATION)
Watermark ✅ Free
Round corners 🟦 Free (radius + background color)

Special

Manipulation Chainsaw Availability
BlurHash ❌
ThumbHash ❌
Dither ❌
Strip EXIF 🟦 Free
Strip ICC 🟦 Free
Max bytes 🟦 Free (auto quality degradation)
No upscale 🟦 Free
Smart cover (native) 🟦 Free (Thumbor’s native cover thumbnail mode — distinct from the Cover resize manipulator above)
AutoJPG 🟦 Free

Encoding

Format Supported
JPEG ✅
PNG ✅
WebP ✅
AVIF ✅
GIF ✅
Auto format ❌
Quality ✅

Notes

  • Gamma, Sepia, Pixelate, Hue, Negate, Border are not available in Thumbor — these manipulators throw UnsupportedManipulator.
  • Cover – cover() (and its crop() alias) accepts compass and smart anchors. focal() throws: Thumbor expects a focal rectangle, not a point. Scale, CropToRatio, and PadToRatio are registered but throw at URL-build time (no scale-by-factor or aspect-ratio-only primitive); specify absolute dimensions via cover()/pad() instead.
  • Stretch – implemented as a Thumbor filter (stretch()), not a path segment.
  • Blur – emits blur(radius, sigma) with an explicit sigma = round(radius / 2); Thumbor defaults sigma to the radius, which would land 2× above the σ ≈ radius/2 anchor shared across providers.
  • Sharpen – amount divided by 10, uses fixed radius 0.3 and luminance-only sharpening.
  • Saturation – throws on .gif sources: Thumbor’s saturation filter silently no-ops on animated GIFs.
  • Watermark – uses watermark({url},{x},{y},{transparency},{w_ratio},{h_ratio}) filter. Negative position values anchor from right/bottom edges. A width/height box emits both ratios so the mark fits inside it keeping aspect; a single axis leaves the other none and scales proportionally.
  • Watermark fit – thumbor fits the mark within its box keeping the aspect ratio, which is WatermarkFit::Contain (the default). Fill, Stretch and Crop have no thumbor equivalent and throw UnsupportedManipulator.
  • Smart crop – Thumbor’s signature feature. Uses content analysis and face detection to find the best crop region.
  • AutoOrient – no-op at URL level; EXIF auto-orientation is controlled server-side via RESPECT_ORIENTATION.
  • Auto format – Format::Auto is silently ignored (skipped in applyEncoding); set an explicit format or compose a <picture> with typed sources.
  • HMAC signing – supported via path prefix.
Previous imgproxy Next Imagor