PHPackages                             renatio/image-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. renatio/image-plugin

ActiveOctober-plugin[Image & Media](/categories/media)

renatio/image-plugin
====================

Manipulate images.

v1.0.1(6mo ago)08[9 issues](https://github.com/mplodowski/image-plugin/issues)proprietaryPHP

Since Dec 8Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/mplodowski/image-plugin)[ Packagist](https://packagist.org/packages/renatio/image-plugin)[ Docs](https://octobercms.com/plugin/renatio-image)[ RSS](/packages/renatio-image-plugin/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (3)Versions (5)Used By (0)

Image plugin
============

[](#image-plugin)

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

[![OctoberCMS Image Plugin](https://camo.githubusercontent.com/70bc61a1608abc8539eace93aafaf09400d0f5924489003b979208dc06cfc394/68747470733a2f2f7669612e706c616365686f6c6465722e636f6d2f383030783430302e706e673f746578743d496d6167652b4d616e6970756c6174696f6e2b506c7567696e)](https://camo.githubusercontent.com/70bc61a1608abc8539eace93aafaf09400d0f5924489003b979208dc06cfc394/68747470733a2f2f7669612e706c616365686f6c6465722e636f6d2f383030783430302e706e673f746578743d496d6167652b4d616e6970756c6174696f6e2b506c7567696e)

Features
--------

[](#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](https://github.com/spatie/image) package

Why is this a paid plugin?
--------------------------

[](#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?
-----------------

[](#like-this-plugin)

If you like this plugin, give this plugin a Like or Make donation with [PayPal](https://www.paypal.me/mplodowski).

My other plugins
----------------

[](#my-other-plugins)

Please check my other [plugins](https://octobercms.com/author/Renatio).

Support
-------

[](#support)

Please use [GitHub Issues Page](https://github.com/mplodowski/image-plugin-public/issues) 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](https://www.flaticon.com/authors/freepik)from [www.flaticon.com](https://www.flaticon.com/).

Documentation
=============

[](#documentation)

Requirements
------------

[](#requirements)

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

Installation
------------

[](#installation)

### Via October CMS Marketplace

[](#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

[](#via-composer)

```
composer require renatio/image-plugin
```

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

```
php artisan october:migrate
```

How It Works
------------

[](#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

[](#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
-----

[](#usage)

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

### Basic Example

[](#basic-example)

```
{# Apply greyscale effect #}

{# Chain multiple filters #}

```

### Responsive Images with WebP

[](#responsive-images-with-webp)

```

```

Available Filters
-----------------

[](#available-filters)

### Brightness

[](#brightness)

Adjust image brightness.

**Parameters:**

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

**Example:**

```
{# Increase brightness #}

{# Decrease brightness #}

```

### Contrast

[](#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

[](#gamma)

Adjust image gamma correction.

**Parameters:**

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

**Example:**

```

```

### Colorize

[](#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:**

```
{# Add red tint #}

{# Add sepia-like tint #}

```

### Blur

[](#blur)

Apply blur effect to image.

**Parameters:**

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

**Example:**

```

```

### Pixelate

[](#pixelate)

Apply pixelation effect to image.

**Parameters:**

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

**Example:**

```
{# Default pixelation #}

{# Custom pixel size #}

```

### Greyscale

[](#greyscale)

Convert image to greyscale (black and white).

**Parameters:** None

**Example:**

```

```

**Alternative spelling:**

```

```

### Sepia

[](#sepia)

Apply sepia tone effect to image.

**Parameters:** None

**Example:**

```

```

### Sharpen

[](#sharpen)

Sharpen image details.

**Parameters:**

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

**Example:**

```

```

### Watermark

[](#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:**

```
{# Use default watermark #}

{# Use custom watermark #}

```

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

### WebP

[](#webp)

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

**Parameters:** None

**Example:**

```
{# Simple conversion #}

{# Use in picture element for progressive enhancement #}

```

### Optimize

[](#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](#optimizer-installation) for details.

### Quality

[](#quality)

Adjust image quality (compression level).

**Parameters:**

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

**Example:**

```
{# High quality for important images #}

{# Lower quality for thumbnails #}

```

### Base64

[](#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:**

```
{# Inline image as data URI #}

{# Specify format #}

{# Without data URI prefix (for CSS or other uses) #}
{% set imageData = 'images/icon.png'|base64('png', false) %}
```

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

### Get Width

[](#get-width)

Get image width in pixels.

**Parameters:** None

**Returns:** int

**Example:**

```
{% set imageWidth = 'images/photo.jpg'|get_width %}
Image width: {{ imageWidth }}px

{# Use in conditional logic #}
{% if 'images/photo.jpg'|get_width > 1200 %}
    This is a large image
{% endif %}
```

### Get Height

[](#get-height)

Get image height in pixels.

**Parameters:** None

**Returns:** int

**Example:**

```
{% set imageHeight = 'images/photo.jpg'|get_height %}
Image height: {{ imageHeight }}px

{# Calculate aspect ratio #}
{% set width = 'images/photo.jpg'|get_width %}
{% set height = 'images/photo.jpg'|get_height %}
{% set aspectRatio = (height / width * 100)|round(2) %}
Aspect ratio: {{ aspectRatio }}%
```

Chaining Filters
----------------

[](#chaining-filters)

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

```
{# Create a vintage photo effect #}

{# Optimize and convert to WebP #}

{# Create blurred background image #}

    Content here

```

**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
-----------------

[](#advanced-examples)

### Responsive Product Images

[](#responsive-product-images)

```
{# Product image with optimization #}

```

### Hero Section with Blurred Background

[](#hero-section-with-blurred-background)

```

        Welcome

```

### Image Gallery with Greyscale Hover Effect

[](#image-gallery-with-greyscale-hover-effect)

```
{% for image in gallery.images %}

{% endfor %}
```

### Portfolio Grid with Watermarks

[](#portfolio-grid-with-watermarks)

```

    {% for item in portfolio.items %}

    {% endfor %}

```

### Dynamic Image Dimensions

[](#dynamic-image-dimensions)

```
{% set imagePath = 'images/product.jpg' %}
{% set width = imagePath|get_width %}
{% set height = imagePath|get_height %}

```

Storage and Caching
-------------------

[](#storage-and-caching)

### Cache Location

[](#cache-location)

Manipulated images are stored in:

```
storage/app/uploads/public/manipulations/

```

### Cache File Naming

[](#cache-file-naming)

Files are named using MD5 hashes to ensure uniqueness:

```
{md5_hash}.{extension}

```

The hash is generated from:

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

### Cache Invalidation

[](#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

[](#manual-cache-clearing)

To clear the image manipulation cache:

```
# Remove all manipulated images
rm -rf storage/app/uploads/public/manipulations/*
```

Or create a backend controller action:

```
use Illuminate\Support\Facades\File;

public function clearImageCache()
{
    $path = storage_path('app/uploads/public/manipulations');

    if (File::isDirectory($path)) {
        File::deleteDirectory($path, true);
        File::makeDirectory($path);
    }

    Flash::success('Image cache cleared successfully');
}
```

Configuration
-------------

[](#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
----------------------

[](#optimizer-installation)

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

### Ubuntu/Debian

[](#ubuntudebian)

```
sudo apt-get install jpegoptim optipng pngquant gifsicle webp
```

### macOS (via Homebrew)

[](#macos-via-homebrew)

```
brew install jpegoptim optipng pngquant gifsicle webp
```

### Windows

[](#windows)

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

```
choco install jpegoptim optipng pngquant gifsicle webp
```

### Verify Installation

[](#verify-installation)

Check if optimizers are available:

```
which jpegoptim optipng pngquant gifsicle cwebp
```

For more details, see [Spatie Image Optimizer documentation](https://github.com/spatie/image-optimizer).

Troubleshooting
---------------

[](#troubleshooting)

### Images not appearing after applying filters

[](#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:**

```
# Check if GD is installed
php -m | grep -i gd

# Check if Imagick is installed
php -m | grep -i imagick

# Fix storage permissions
chmod -R 775 storage/app/uploads/public/manipulations/
chown -R www-data:www-data storage/app/uploads/public/manipulations/
```

### "File not found" errors

[](#file-not-found-errors)

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

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

```
{# ✅ Correct #}

{# ❌ Incorrect - absolute path #}

```

### Filter returns original image unchanged

[](#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`:

```
'debug' => true,
```

Check October CMS log files:

```
tail -f storage/logs/system.log
```

### Optimized images not smaller

[](#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](#optimizer-installation)).

### Watermark not appearing

[](#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:**

```
{# Verify watermark file exists #}
{% if 'themes/demo/assets/images/watermark.png'|file_exists %}

{% endif %}
```

### High memory usage

[](#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`:

```
memory_limit = 256M
```

Or temporarily in your code:

```
ini_set('memory_limit', '256M');
```

Consider resizing large images before applying filters:

```
{# Use October's |resize filter first #}

```

### WebP conversion not working

[](#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:

```
# For GD
php -r "var_dump(function_exists('imagewebp'));"

# For Imagick
php -r "var_dump(in_array('WEBP', \Imagick::queryFormats()));"
```

Install WebP libraries:

```
# Ubuntu/Debian
sudo apt-get install libwebp-dev

# Rebuild PHP with WebP support or install/enable imagick extension
```

### Permission denied errors

[](#permission-denied-errors)

**Problem:** Can't write to cache directory.

**Solution:**

```
# Create directory if it doesn't exist
mkdir -p storage/app/uploads/public/manipulations

# Set correct permissions
chmod -R 775 storage/app/uploads/public/manipulations/
chown -R www-data:www-data storage/app/uploads/public/manipulations/

# For development (less secure, don't use in production)
chmod -R 777 storage/app/uploads/public/manipulations/
```

Testing
-------

[](#testing)

The plugin includes comprehensive tests using Pest PHP.

### Running Tests

[](#running-tests)

```
# Run all Image plugin tests
php artisan test --testsuite="Image Plugin"

# Run specific test file
php artisan test plugins/renatio/image/tests/Unit/Classes/ImageManipulationTest.php

# Run with coverage
php artisan test --testsuite="Image Plugin" --coverage
```

For detailed testing documentation, see [tests/README.md](tests/README.md).

Performance Considerations
--------------------------

[](#performance-considerations)

### Best Practices

[](#best-practices)

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

    ```
    {# Good for web #}

    ```
2. **Chain filters efficiently**: Order filters to minimize processing

    ```
    {# Optimize last #}

    ```
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

[](#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)
---------------

[](#api-usage-php)

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

```
use Renatio\Image\Classes\ImageManipulation;

$imageManipulation = new ImageManipulation();

// Apply brightness
$brightImage = $imageManipulation->brightness('path/to/image.jpg', 30);

// Apply blur
$blurredImage = $imageManipulation->blur('path/to/image.jpg', 20);

// Get image dimensions
$width = $imageManipulation->getWidth('path/to/image.jpg');
$height = $imageManipulation->getHeight('path/to/image.jpg');

// Convert to WebP
$webpImage = $imageManipulation->webp('path/to/image.jpg');
```

Credits
-------

[](#credits)

This plugin is built on top of these excellent packages:

- [Spatie Image](https://github.com/spatie/image) - Image manipulation library
- [Spatie Image Optimizer](https://github.com/spatie/image-optimizer) - Image optimization
- [Intervention Image](https://image.intervention.io/) - Underlying image processing (used by Spatie Image)

License
-------

[](#license)

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

Changelog
---------

[](#changelog)

See [UPGRADE.md](UPGRADE.md) for version history and upgrade notes.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance76

Regular maintenance activity

Popularity4

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

207d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6774277?v=4)[Michał Płodowski](/maintainers/mplodowski)[@mplodowski](https://github.com/mplodowski)

---

Top Contributors

[![mplodowski](https://avatars.githubusercontent.com/u/6774277?v=4)](https://github.com/mplodowski "mplodowski (7 commits)")

---

Tags

phplaravelimagewatermarkoptimizerWebpoctobercmsoctobercms-plugin

### Embed Badge

![Health badge](/badges/renatio-image-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/renatio-image-plugin/health.svg)](https://phpackages.com/packages/renatio-image-plugin)
```

###  Alternatives

[rainlab/pages-plugin

Pages plugin for October CMS

12253.8k4](/packages/rainlab-pages-plugin)[rainlab/user-plugin

User plugin for October CMS

11955.0k15](/packages/rainlab-user-plugin)[helsingborg-stad/municipio

A bootstrap theme for creating municipality sites.

4028.5k10](/packages/helsingborg-stad-municipio)[renatio/dynamicpdf-plugin

October HTML to PDF converter using dompdf library.

3013.5k3](/packages/renatio-dynamicpdf-plugin)[finller/laravel-media

A flexible media library for Laravel

472.1k](/packages/finller-laravel-media)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)