README

Description

Image Transformer provides a small service for validating, resizing, and optimizing uploaded images.

It uses Laravel's image service, backed by Intervention Image, for resize operations and Spatie's image optimizer for post-processing, while enforcing a limited set of supported image mime types before any transformation is attempted.

The package is useful in upload flows where images should be normalized before storage, for example avatars, covers, gallery images, or document attachments that need size limits and optimization.

Installation

Install the package:

composer require laravel-enso/image-transformer

The package requires Laravel 13.20 or newer and relies on:

Laravel's image service and intervention/image 4 for reading and resizing images
spatie/laravel-image-optimizer for optimization

To use resizing, the runtime must have at least one supported image extension installed:

gd
imagick

Features

Validates uploaded files before transformation.
Supports png, jpeg, gif, and webp images.
Optimizes images in place through Spatie's optimizer chain.
Resizes images proportionally by width, by height, or by both through resize().
Prevents upsizing by only resizing when the original image is larger than the requested dimension.
Upscales images proportionally to minimum dimensions through upscaleTo().
Encodes transformed images as JPEG bytes through toJpeg().
Saves downscale transformations back to the original file path while keeping upscale and encoding operations in memory.
Keeps chained width and height transformations in one processing pipeline to avoid intermediate re-encoding.
Preserves the previous default encoding quality for in-place transformations.

Usage

Create a transformer from an uploaded file:

use LaravelEnso\ImageTransformer\Services\ImageTransformer;

$transformer = new ImageTransformer($file);

Optimize the original file:

$transformer->optimize();

Resize proportionally to a maximum width:

$transformer->width(512);

Resize proportionally to a maximum height:

$transformer->height(512);

Apply both constraints in sequence:

$transformer->resize(1024, 768);

Upscale proportionally until both minimum dimensions are reached, then encode the result as JPEG without modifying the original file:

$contents = $transformer
    ->upscaleTo(500, 500)
    ->toJpeg(quality: 85);

::: tip Tip The transformer edits the original file in place.

If you need to preserve the original upload, copy or move it before calling optimize(), width(), height(), or resize().

upscaleTo() and toJpeg() operate in memory and do not modify the original file. :::

API

Service

LaravelEnso\ImageTransformer\Services\ImageTransformer

Constructor:

__construct(File $file)

Public methods:

optimize(): self
resize(int $width, int $height): self
upscaleTo(int $width, int $height): self
toJpeg(int $quality = 85): string
width(int $width): self
height(int $height): self

Supported Mime Types

The service accepts:

image/png
image/jpeg
image/gif
image/webp

Exceptions

The package exposes:

LaravelEnso\ImageTransformer\Exceptions\File
LaravelEnso\ImageTransformer\Exceptions\Dependency

Scenarios covered:

invalid uploaded file
unsupported mime type
missing gd / imagick extension when resizing

Depends On

Required Enso packages:

laravel-enso/helpers ↗

External dependencies:

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!

laravel-enso / image-transformer

Maintainers

Package info

Statistics

Security