README

Easy, URL-based image transformations inspired by Cloudflare Images.

Features:

✈️ Use URL parameters to transform images on the fly
🔧 Support for various transformations like resizing, compression, and format conversion
⚡ Automatic caching of transformed images for faster loading times
🌍 Easy integration with CDNs for even faster global delivery

Requirements

PHP >= 8.4
Laravel 12.x

If you want to use the file caching feature (highly recommended), a configured Storage disk and a Cache driver is required. More info in the Image Caching section.

Important

It is highly recommended to set a minimum memory limit of 256MB in your php.ini file to avoid memory issues when images are being processed.

Installation

Install the package via composer:

composer require ace-of-aces/laravel-image-transform-url

Publish the config file with:

php artisan vendor:publish --tag="image-transform-url-config"

Usage

Configure the package via image-transform-url.php to set your public_path directory, from where you want to transform the images. It is recommended to use a dedicated directory for your images in order to have a separation of concerns.
Test your first image transformation:

Use the following URL format to transform your images:

http://<domain>/<route-prefix>/<options>/<path-to-your-image.<jpg|jpeg|png|gif|webp>>

for example:

http://localhost:8000/image-transform/width=250,quality=80,format=webp/foo/bar/example.jpg

Options

Note

The options are separated by commas and their values are appended with equal signs. The order of options does not matter.

Option	Description	Type	Description / Possible Values
`width`	Set the width of the image.	integer	Values greater than the original width will be ignored.
`height`	Set the height of the image.	integer	Values greater than the original height will be ignored.
`quality`	Set the quality of the image.	integer	`0` to `100`
`format`	Set the format of the image.	string	Supported formats: `jpg`, `jpeg`, `png`, `gif`, `webp`.
`blur`	Set the blur level of the image.	integer	`0` to `100`
`contrast`	Set the contrast level of the image.	integer	`-100` to `100`
`flip`	Flip the image.	string	`h`(horizontal), `v`(vertical), `hv`(horizontal and vertical)
`version`	Version number of the image.	integer	Any positive integer. More info in the Image Caching section.

Caution

The blur option is a resource-intensive operation and may cause memory issues if the image is too large. It is recommended to use this option with caution, or disable it in the config.

Image Caching

This package comes with the default option to automatically store and serve images statically for the requested options within the caching lifetime.

Note

Having this feature enabled (default behavior) will help to reduce the load on your server and speed up image delivery.

The processed images are stored in the storage/app/private/_cache/image-transform-url directory by default. You can change the disk configuration in the image-transform-url.php configuration file.

Caution

When using this option, there is one caveat to be aware of:

Source images are considered to be stale content by their file name and path.

If the content of an original source image changes, but the file name stays the same, the cached images will not be updated automatically until the cache expires. To force a revalidation, you can either:

change the image's file name
move it into another subdirectory, which will change its path
change the version number (integer) in the options (e.g. version=2)
or flush the entire cache of your application using the php artisan cache:clear command.

Rate Limiting

Another feature of this package is the ability to limit the number of transformations that the image transformation route should process per path and IP address within a given time frame.

The rate limit will come into effect for new transformation requests only, and will not affect previously cached images.

By default, rate limiting is disabled for the local and testing app environements to not distract you when developing your app. You can configure the rate limit settings in the image-transform-url.php configuration file.

Usage with CDNs

The package is designed to work seamlessly with CDNs like Cloudflare, BunnyCDN, and others.

The most important configuration is the Cache-Control header, which you can customize to your liking in the image-transform-url.php configuration file.

Error Handling

The route handler of this package is designed to be robust against invalid options, paths and file names, while also not exposing additional information of your applications public directory structure.

This is why the route handler will return a 404 response if:

a requested image does not existn at the specified path
the requested image is not a valid image file
the provided options are not in the correct format (key=value, no trailing comma, etc.)

The only other HTTP error that can be returned is a 429 response, which indicates that the request was rate-limited.

If parts of the given route options are invalid, the route handler will ignore them and only apply the valid options.

Example:

http://localhost:8000/image-transform/width=250,quality=foo,format=webp/example.jpg

will be processed as:

http://localhost:8000/image-transform/width=250,format=webp/example.jpg

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

Aaron Francis for the original idea and foundational work
Cloudflare Images for the URL-Syntax structure
Intervention Image for the underlying image processing

License

The MIT License (MIT). Please see License File for more information.

ace-of-aces / laravel-image-transform-url

Maintainers

Details