5.3 KiB

Raw Blame History

Image Optimization

The package provides on-the-fly image resizing with caching, WebP conversion, and configurable quality. Requires spatie/image.

Requirements

composer require spatie/image "^3.8"

If spatie/image is not installed, all resizing calls gracefully return the original file path.

Resizing via URL

When serving images through the Warehouse, append query parameters:

/warehouse/{id}?size=300x200
/warehouse/{id}?size=400&quality=90
/warehouse/{id}?size=800x600&webp=false&position=contain

Query Parameters

Param	Type	Default	Description
`size`	`string`	—	Dimensions as `WIDTHxHEIGHT` (e.g. `300x200`). Use a single number for square (e.g. `300`).
`quality`	`int`	`85`	JPEG/WebP quality (1–100)
`webp`	`bool`	`true`	Convert output to WebP
`position`	`string`	`cover`	Fit mode: `cover`, `contain`, `fill`, `max`, `stretch`
`cached`	`bool`	`true`	Use cached resize if available
`rounding`	`bool`	`true`	Round dimensions to nearest step

Resizing Programmatically

Use the resizedPath() method to generate a resized variant:

$path = $file->resizedPath(
    width: 300,
    height: 200,
    toWebp: true,
    quality: 85,
    position: 'cover',
);

Parameters

Parameter	Type	Default	Description
`$width`	`string\|int\|null`	—	Target width. Use `'auto'` for proportional.
`$height`	`string\|int\|null`	—	Target height. Use `'auto'` for proportional.
`$rounding`	`bool`	`true`	Round to nearest step (default: 50px)
`$toWebp`	`bool`	`true`	Convert to WebP format
`$cached`	`bool`	`true`	Return cached version if available
`$quality`	`?int`	`null`	Quality (1–100). `null` uses config default.
`$position`	`string`	`'cover'`	Fit mode

The method returns an absolute file path to the resized image.

Fit Modes

Mode	Behavior
`cover`	Crop to fill exact dimensions (default)
`contain`	Fit within dimensions, preserving aspect ratio
`fill`	Fill dimensions, padding if necessary
`max`	Resize within dimensions, no upscaling
`stretch`	Stretch to exact dimensions

Caching

Resized images are cached on disk in a resized/ subdirectory next to the original:

files/2024/06/15/abc-123            ← original
files/2024/06/15/resized/
    abc-123.300x200.jpg.webp        ← resized variant
    abc-123.800x600.contain.q90.jpg ← another variant

Cache key components: {width}x{height}, .{position} (if not cover), .q{quality} (if not default). Requesting the same size again serves from cache instantly.

When a file is deleted, all resized variants are cleaned up automatically.

Dimension Rounding

To reduce cache fragmentation, dimensions are rounded up to the nearest step (default: 50px):

Requested	Rounded to
`280x180`	`300x200`
`310x310`	`350x350`
`50x50`	`50x50`

Configure the step size:

// config/files.php
'optimization' => [
    'round_to' => 100, // round to nearest 100px
],

Disable rounding per request with ?rounding=false or rounding: false.

Skipped Formats

Some formats cannot be processed by image libraries and are served as-is:

'optimization' => [
    'skip_formats' => ['gif', 'svg', 'svg+xml'],
],

Preferred Extensions (Asset Auto-Resolution)

When the warehouse receives a path without an extension (e.g. /warehouse/images/logo), it tries these extensions in order:

'optimization' => [
    'preferred_extensions' => ['svg', 'webp', 'png', 'jpg', 'jpeg'],
],

Configuration Reference

All optimization settings in config/files.php:

'optimization' => [
    'enabled'              => true,
    'default_quality'      => 85,       // default JPEG/WebP quality
    'webp_conversion'      => true,     // convert to WebP by default
    'round_dimensions'     => true,     // round sizes to reduce cache variants
    'round_to'             => 50,       // rounding step in pixels
    'skip_formats'         => ['gif', 'svg', 'svg+xml'],
    'preferred_extensions' => ['svg', 'webp', 'png', 'jpg', 'jpeg'],
],

Next: Configuration

5.3 KiB Raw Blame History Unescape Escape