Download the PHP package renatio/image-plugin without Composer

Image plugin

Plugin provides powerful Twig filters for manipulating images on-the-fly with automatic caching and optimization.

Features

• Easy-to-use Twig filters for image manipulation
• Automatic caching of manipulated images
• Built-in image optimization
• WebP format conversion
• Watermark support
• Multiple image effects (blur, pixelate, greyscale, sepia, sharpen)
• Color adjustments (brightness, contrast, gamma, colorize)
• Quality control
• Image dimension getters
• Base64 encoding support
• No backend UI required - works directly in templates
• Based on robust Spatie Image package

Why is this a paid plugin?

Something that is free has little or no perceived value. Users do not commit to free products and only use them until something else looks nice and is free comes along. When I invest my time in the development of a new plugin I commit to supporting and maintaining it. I ask my customers to do the same. I do not make money from this plugin by advertisements, upgrades or additional services like hosting or setup.

Did you know that 30% of your purchase or donation goes to help fund the October Project?

My plugins take many hours to develop (40-120+) and even more hours to document and maintain. My paid plugins have to pay for both this time, and the time I am spending on free plugins and less successful paid plugins. This means that it will take even a successful plugin years to become profitable. Please consider buying an extended license if you want me to continue to maintain these plugins for the very small fee I ask in return or hire me for adding functionality that you feel is missing but valuable.

Like this plugin?

If you like this plugin, give this plugin a Like or Make donation with PayPal.

My other plugins

Please check my other plugins.

Support

Please use GitHub Issues Page to report any issues with plugin.

Reviews should not be used for getting support, if you need support please use the Plugin support link.

Icon made by Freepik from www.flaticon.com.

Documentation

Requirements

• October CMS v4.0 or higher
• PHP 8.2 or higher
• GD or Imagick PHP extension
• Composer

Installation

Via October CMS Marketplace

1. Navigate to Settings → Updates & Plugins in your October CMS backend
2. Click Install plugins
3. Search for "Renatio Image"
4. Click Install

Via Composer

After installation, run the migrations (although this plugin doesn't require database tables):

How It Works

The Image plugin registers Twig filters that you can use directly in your templates. When you apply a filter to an image:

1. The plugin checks if a manipulated version already exists in the cache
2. If not, it creates the manipulated image using the Spatie Image library
3. The manipulated image is automatically optimized
4. The result is saved to storage/app/uploads/public/manipulations/
5. Subsequent requests serve the cached version for optimal performance

Caching Strategy

Cached file names are generated using MD5 hashing based on:

• Original image path
• Manipulation type
• Manipulation parameters
• Original file modification time

This ensures that:

• Cache is automatically invalidated when source images change
• Different manipulations of the same image are cached separately
• Cache files have unique, collision-free names

Usage

All filters are available in Twig templates. Simply pipe your image path through any filter:

Basic Example

Responsive Images with WebP

Available Filters

Brightness

Adjust image brightness.

Parameters:

• brightness (int): Brightness level from -100 (darker) to +100 (brighter)

Example:

Contrast

Adjust image contrast.

Parameters:

• level (float): Contrast level. Use values like 0.5 (low contrast), 1.0 (normal), 1.5 (high contrast)

Example:

Gamma

Adjust image gamma correction.

Parameters:

• gamma (float): Gamma value. Typical range: 0.1 to 3.0

Example:

Colorize

Apply color tint to image.

Parameters:

• red (int): Red channel adjustment (-255 to +255)
• green (int): Green channel adjustment (-255 to +255)
• blue (int): Blue channel adjustment (-255 to +255)

Example:

Blur

Apply blur effect to image.

Parameters:

• blur (int): Blur amount (0-100, higher values = more blur)

Example:

Pixelate

Apply pixelation effect to image.

Parameters:

• pixelate (int, optional): Pixel block size. Default: 50

Example:

Greyscale

Convert image to greyscale (black and white).

Parameters: None

Example:

Alternative spelling:

Sepia

Apply sepia tone effect to image.

Parameters: None

Example:

Sharpen

Sharpen image details.

Parameters:

• amount (float): Sharpening amount (typical range: 10-50)

Example:

Watermark

Add watermark image overlay.

Parameters:

• watermarkImage (string, optional): Path to watermark image. Default: themes/demo/assets/images/watermark.png
• options (array, optional): Additional watermark options (position, opacity, etc.)

Example:

Note: Watermark positioning options are currently being developed. The watermark will be placed according to Spatie Image defaults.

WebP

Convert image to WebP format for better compression and web performance.

Parameters: None

Example:

Optimize

Optimize image file size without quality loss using image optimizers.

Parameters: None

Example:

Note: This filter uses the Spatie Image Optimizer package which requires system-level optimizer binaries (optipng, pngquant, jpegoptim, etc.). See Installation Requirements for details.

Quality

Adjust image quality (compression level).

Parameters:

• quality (int): Quality level (1-100, where 100 is highest quality/largest file size)

Example:

Base64

Encode image as Base64 data URI for embedding directly in HTML.

Parameters:

• imageFormat (string, optional): Output format ('jpeg', 'png', 'gif', 'webp'). Default: 'jpeg'
• prefixWithFormat (bool, optional): Include data URI prefix. Default: true

Example:

Best Practice: Only use Base64 encoding for small images (icons, small logos) to avoid bloating your HTML.

Get Width

Get image width in pixels.

Parameters: None

Returns: int

Example:

Get Height

Get image height in pixels.

Parameters: None

Returns: int

Example:

Chaining Filters

You can chain multiple filters together to create complex image manipulations:

Performance Note: Each filter in the chain creates a new manipulation. The plugin caches the final result, so chained filters don't impact runtime performance on subsequent requests.

Advanced Examples

Responsive Product Images

Hero Section with Blurred Background

Image Gallery with Greyscale Hover Effect

Portfolio Grid with Watermarks

Dynamic Image Dimensions

Storage and Caching

Cache Location

Manipulated images are stored in:

Cache File Naming

Files are named using MD5 hashes to ensure uniqueness:

The hash is generated from:

• Original image path
• Manipulation type
• Manipulation parameters
• Source file modification time

Cache Invalidation

The cache is automatically invalidated when:

• The source image is modified (detected via file modification time)
• You manually delete the cached files

Manual Cache Clearing

To clear the image manipulation cache:

Or create a backend controller action:

Configuration

Currently, the plugin uses hardcoded defaults. Configuration options may be added in future versions for:

• Cache directory path
• Optimization timeout (currently 120 seconds)
• Global optimization toggle
• Default watermark image path
• Default quality settings

Optimizer Installation

The optimize filter requires system-level image optimizer binaries to be installed on your server.

Ubuntu/Debian

macOS (via Homebrew)

Windows

Download and install optimizers manually, or use tools like Chocolatey:

Verify Installation

Check if optimizers are available:

For more details, see Spatie Image Optimizer documentation.

Troubleshooting

Images not appearing after applying filters

Possible causes:

1. Source image path is incorrect
2. GD or Imagick extension not installed
3. Insufficient disk space
4. Permission issues with storage directory

Solutions:

"File not found" errors

Problem: The plugin can't find the source image.

Solution: Always use paths relative to your October CMS base directory:

Filter returns original image unchanged

Possible causes:

1. Exception occurred during processing (silently caught)
2. Source file doesn't exist
3. Image manipulation failed

Debug: Enable October CMS debug mode in config/app.php:

Check October CMS log files:

Optimized images not smaller

Problem: The optimize filter doesn't reduce file size significantly.

Possible causes:

1. Optimizers not installed on the system
2. Images already optimized
3. Optimizer binaries not in system PATH

Solution: Verify optimizers are installed (see Optimizer Installation).

Watermark not appearing

Problem: Watermark filter doesn't show the watermark.

Possible causes:

1. Watermark image path is incorrect
2. Watermark image doesn't exist
3. Watermark positioning options need to be configured

Solution:

High memory usage

Problem: Image manipulation causes memory errors.

Possible causes:

1. Processing very large images
2. PHP memory limit too low

Solutions:

Increase PHP memory limit in php.ini:

Or temporarily in your code:

Consider resizing large images before applying filters:

WebP conversion not working

Problem: WebP filter doesn't convert images.

Possible causes:

1. GD or Imagick doesn't support WebP
2. WebP libraries not installed

Solutions:

Verify WebP support:

Install WebP libraries:

Permission denied errors

Problem: Can't write to cache directory.

Solution:

Testing

The plugin includes comprehensive tests using Pest PHP.

Running Tests

For detailed testing documentation, see tests/README.md.

Performance Considerations

Best Practices

1. Use appropriate quality settings: Balance file size and visual quality

2. Chain filters efficiently: Order filters to minimize processing

3. Leverage caching: The first request processes the image; subsequent requests serve from cache

4. Use WebP for modern browsers: Significantly smaller file sizes

5. Avoid processing very large images: Resize before manipulating if possible

Cache Performance

• First request: ~100-500ms (depending on image size and manipulations)
• Cached requests: ~1-5ms (serving static files)
• Storage impact: Manipulated images are stored permanently until cache is cleared

API Usage (PHP)

While designed for Twig templates, you can use the ImageManipulation class directly in PHP:

Credits

This plugin is built on top of these excellent packages:

• Spatie Image - Image manipulation library
• Spatie Image Optimizer - Image optimization
• Intervention Image - Underlying image processing (used by Spatie Image)

License

This is a proprietary commercial plugin. License is granted per October CMS installation.

Changelog

See UPGRADE.md for version history and upgrade notes.