Resize & Fit

The Chainsaw API for resize, crop, fit, and aspect-ratio operations. For the conceptual catalogue (vendor-neutral, with comparison tables), see Resize Modes.

crop() is a Spatie-style alias of cover() — same signature, same behaviour. Pick whichever name reads better at the call site.

width(int $width)

Baseline Supported on all 10 providers.

CFCNIMIMIMIXIPIVTHWS

Scale to a specific width, preserving aspect ratio.

$image->width(400);

height(int $height)

Baseline Supported on all 10 providers.

CFCNIMIMIMIXIPIVTHWS

Scale to a specific height, preserving aspect ratio.

$image->height(300);

scale(float $factor)

Limited availability Only supported on Cloudinary, Imagine and Intervention.

CFCNIMIMIMIXIPIVTHWS

Multiply both dimensions by the same factor. 0.5 halves the image; 2 doubles it.

$image->scale(0.5);
$image->scale(2.0);

contain(int $width, int $height, bool $noUpscale = false)

Baseline Supported on all 10 providers.

CFCNIMIMIMIXIPIVTHWS

Scale to fit inside a box, preserving aspect ratio. Output is ≤ box on each axis. noUpscale: true caps the output at source dimensions (the old scaleDown() behaviour).

$image->contain(400, 400);
$image->contain(400, 400, noUpscale: true);

pad(int $width, int $height, string $background = '#ffffff', bool $noUpscale = false)

Baseline Supported on all 10 providers.

CFCNIMIMIMIXIPIVTHWS

Resize to fit inside a box (preserving aspect), then fill the empty area with a background colour. Output dimensions equal the box exactly.

$image->pad(400, 400, '#2a2a2a');
$image->pad(400, 400, '#fff', noUpscale: true);

stretch(int $width, int $height)

Baseline Supported on all 10 providers.

CFCNIMIMIMIXIPIVTHWS

Force exact dimensions, ignoring aspect ratio. Distorts the source.

$image->stretch(300, 300);

cover(int $width, int $height, CropPosition|Anchor|null $anchor = null, bool $noUpscale = false)

Baseline Supported on all 10 providers.

CFCNIMIMIMIXIPIVTHWS

Scale the source so it covers the entire box, preserving aspect, then crop the overflow on the long axis. Output dimensions equal the box exactly. The crop position is configurable via the anchor argument: a CropPosition enum value (the 9 compass points) or any Anchor (focal point, smart, face, entropy, attention, object class).

use Timber\Chainsaw\Anchor;
use Timber\Chainsaw\Enum\CropPosition;

$image->cover(800, 600);                                   // centred (default)
$image->cover(800, 600, CropPosition::TopLeft);            // compass anchor
$image->cover(800, 600, Anchor::focal(0.7, 0.4));          // focal point
$image->cover(800, 600, Anchor::focal(0.7, 0.4, zoom: 1.5));// focal + zoom
$image->cover(800, 600, Anchor::smart());                  // saliency / auto
$image->cover(800, 600, Anchor::entropy());                // entropy crop
$image->cover(800, 600, Anchor::attention());              // attention crop
$image->cover(800, 600, Anchor::face());                   // face detection
$image->cover(800, 600, Anchor::object('dog'));            // object-class detection
$image->cover(800, 600, noUpscale: true);                  // never enlarge

Anchor::smart() enables content-aware smart cropping — supported by most cloud providers. Providers without smart-crop support throw UnsupportedManipulator.

Anchor::object() is supported by Cloudinary (g_auto:<class>) and imgproxy Pro (obj:<class>); other providers throw.

crop() — alias of cover()

For PHP-ecosystem familiarity (Spatie-style), crop() is a one-liner alias. Identical signature, identical behaviour.

$image->crop(800, 600);                                    // same as cover(800, 600)
$image->crop(800, 600, CropPosition::Top);
$image->crop(800, 600, Anchor::face());

manualCrop(int $width, int $height, int $x, int $y)

Baseline Supported on all 10 providers.

CFCNIMIMIMIXIPIVTHWS

Crop at absolute pixel coordinates. Specify the crop window’s size and top-left offset.

$image->manualCrop(400, 300, 100, 50);  // 400×300 box at (100, 50)

cropToRatio(string|Ratio $ratio, CropPosition|Anchor|null $anchor = null)

Limited availability Only supported on Cloudinary, Imagekit, Imagine, Imgix and Intervention.

CFCNIMIMIMIXIPIVTHWS

Crop to a target aspect ratio. Output dimensions are derived from the source — the largest rectangle of the target ratio that fits inside the source is cut.

use Timber\Chainsaw\Anchor;
use Timber\Chainsaw\Geometry\Ratio;

$image->cropToRatio('16:9');                              // string form
$image->cropToRatio(new Ratio(16, 9));                    // typed form
$image->cropToRatio('16:9', Anchor::smart());             // smart-anchored

padToRatio(string|Ratio $ratio, string $background = '#ffffff')

Limited availability Only supported on Cloudinary, Imagekit, Imagine, Imgix and Intervention.

CFCNIMIMIMIXIPIVTHWS

Extend the canvas to a target aspect ratio with a background colour. Source pixels are preserved at their original size; only the surrounding canvas grows.

$image->padToRatio('16:9');
$image->padToRatio('16:9', '#000000');

trim(int $tolerance = 10, ?string $color = null)

Widely available Unsupported on Imagine.

CFCNIMIMIMIXIPIVTHWS

Remove border pixels that match a reference colour. By default the reference colour is auto-detected from the image corners; pass $color to specify it explicitly.

$image->trim();                    // auto-detect border colour
$image->trim(30);                  // higher tolerance (0..100)
$image->trim(10, '#ffffff');       // trim white borders explicitly

Tolerance is 0 (exact match only) to 100 (aggressive). Chainsaw maps the value to each provider’s native range.

Explicit colour is supported by Cloudflare, Cloudinary, imgix, imgproxy, and wsrv.nl. Thumbor, Imagor, and Intervention ignore it and auto-detect.