Download the PHP package ace-of-aces/laravel-image-transform-url without Composer

Laravel Image Transform URL

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:

Publish the config file with:

Usage

1. 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.

2. Test your first image transformation:

Use the following URL format to transform your images:

for example:

Options

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

[!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:

1. change the image's file name
2. move it into another subdirectory, which will change its path
3. change the version number (integer) in the options (e.g. version=2)
4. 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:

will be processed as:

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.