Presets

A preset is a named, reusable recipe: a bundle of manipulators plus an optional Encoding (format and quality). You register presets on the factory once and apply them by name, so a “thumbnail” or “hero” transform lives in one place instead of being retyped at every call site.

A preset spans two concerns on purpose — manipulations and encoding — which is why it has its own page rather than living under either.

Defining presets

A Preset takes a name, a list of manipulators, and an optional Encoding:

use Timber\Chainsaw\Encoding;
use Timber\Chainsaw\Enum\Format;
use Timber\Chainsaw\Manipulator\Crop;
use Timber\Chainsaw\Preset;
use Timber\Chainsaw\Presets;

$presets = (new Presets())
    ->add(new Preset('thumbnail', [new Crop(200, 200)]))
    ->add(new Preset(
        'hero',
        [new Crop(1200, 600)],
        new Encoding(format: Format::Webp, quality: 85),
    ));

Register them on the factory:

use Timber\Chainsaw\ImageFactory;

$factory = new ImageFactory(provider: $provider, presets: $presets);

Applying a preset

Call preset() by name, anywhere in the chain:

$factory->image('photo.jpg')->preset('hero');

In Twig it is a filter like any other manipulation:

{{ 'photo.jpg'|preset('hero')|img(alt: 'Hero') }}

How a preset composes

preset() is a normal chain step, not a reset. It applies the preset’s manipulators one by one (through the same normalization every manipulator goes through) and merges its encoding into whatever the image already carries:

• It composes with the rest of the chain. Ops before and after the preset both apply. A resize inside the preset folds with a resize elsewhere in the chain under the single-resize-intent rule (see Resize modes); it does not stack a second competing resize.
• Encoding merges, last write wins per field. A quality() set after the preset overrides the preset’s quality; a preset with no Encoding leaves the current format and quality untouched.

// preset's Crop(1200, 600) + WebP, then quality overridden to 60
$factory->image('photo.jpg')->preset('hero')->quality(60);

When to reach for a preset

Presets are for a fixed, named recipe reused across call sites — a design system’s image sizes (avatar, card, hero). For a computed or one-off transform, chain the manipulators directly. A preset only bundles manipulators and encoding, not provider or cache wiring.