Image transforms
Published
Reviewedbyfl
🖼️
Resize in the background.
Image transforms are behind many 504 errors and memory kills on CMS sites. Crunch images in a background worker, not in the PHP processes that serve the site, and keep the source images small.
About image transforms
Most CMS and many apps create resized copies of uploaded images: thumbnails, responsive sizes, WebP or AVIF versions. Each copy is a transform. PHP loads the full source image into memory and resizes it with GD or ImageMagick. A 6000 pixel camera photo takes about nine times the memory of a 2000 pixel one, and one upload can trigger many transforms at once, one per size and format. With files on S3 or another remote storage, PHP also downloads the source and uploads every result.
When that runs in the PHP processes that serve the site, requests run into the timeout and return a 504 error, or a process runs out of memory. Other visitors wait for a free PHP process meanwhile.
Crunch images in a worker
We recommend a worker job for image transforms. The worker runs the queue of the app in its own container: it resizes images in the background while the PHP processes keep serving visitors. Image optimizers such as jpegoptim or pngquant are installed in jobs only, so they run there too.
- Book the jobs component.
- Set up the queue of the app, so transforms become queue jobs instead of running in the request.
- Add a worker job with the queue command of the software.
- Turn off queue processing in web requests, where the software has it.
| Software | Worker command | Path |
|---|---|---|
| Craft CMS | php craft queue/listen --verbose | Craft CMS image transforms |
| Laravel | php artisan queue:work | Laravel image conversions |
| Statamic | php artisan queue:work | Statamic image presets |
| Kirby | Plugin, untested | Kirby thumbs |
| WordPress | Plugin, untested | WordPress image sizes |
When transforms run
Without a worker, transforms run in a web request:
| Trigger | Runs in |
|---|---|
| Upload | The upload request |
| First view of the image URL | That image request |
| Page render | The page request |
| Queue processed by web requests | A page request |
Transforms triggered by a URL can also be triggered by bots, and they fill the storage.
Keep source images small
A worker still needs memory for every image.
- Scale images down before uploading them. Twice the largest display size is enough for high-density screens.
- Define fewer sizes and formats. Every combination is another file to generate and store. Page weight covers the ones worth generating.