Gumlet Asset Transformer for Craft CMS

Transform your Craft CMS images using Gumlet's powerful image transformation service. This plugin provides a seamless integration that replaces Craft's native image transforms with Gumlet's on-the-fly image processing, giving you access to advanced image optimization and transformation features.

Features

• Drop-in Replacement: Works seamlessly with Craft CMS native image transforms and .srcset() method
• Multiple Usage Methods: Choose from Twig function, service method, or automatic transformer
• Type-Safe Parameters: Only valid ImageTransform properties are accepted, preventing errors
• Additional Gumlet Parameters: Apply advanced Gumlet transformations (blur, brightness, contrast, etc.)
• PDF Support: Rasterize and transform PDF files (unlike Craft CMS native transforms)
• Automatic Format Optimization: Support for WebP, AVIF, and other modern formats
• CP Thumbnails: Use Gumlet for Control Panel thumbnails
• Zero Configuration Required: Works out of the box with minimal setup

Requirements

• Craft CMS 4.0.0 or later
• PHP 8.0.2 or later
• A Gumlet account and domain

Installation

1. Install the plugin via Composer:

composer require gumlet/craft-gumlet-imagetransformer

1. Install the plugin in Craft CMS:

php craft plugin/install gumlet-imagetransformer

1. Copy the config file:

cp vendor/gumlet/craft-gumlet-imagetransformer/src/config.php config/gumlet-imagetransformer.php

1. Update your config/gumlet-imagetransformer.php with your Gumlet domain:

return [
    'gumletDomain' => 'your-domain.gumlet.io',
    'enabled' => true,
    'defaultQuality' => 80,
    'defaultFormat' => 'auto',
];

Usage

Method 1: Twig Function (Recommended)

The easiest way to generate Gumlet URLs:

{# Basic usage #}
<img src="{{ gumletUrl(asset, { width: 300, height: 300 }) }}" alt="{{ asset.title }}" />

{# With additional Gumlet parameters #}
<img src="{{ gumletUrl(asset, { width: 300, height: 300 }, { blur: 10, brightness: 5 }) }}" alt="{{ asset.title }}" />

{# With quality and format #}
<img src="{{ gumletUrl(asset, { width: 500, height: 500, quality: 85, format: 'webp' }) }}" alt="{{ asset.title }}" />

Method 2: Service Method

Use the Gumlet service directly:

{# Basic usage #}
<img src="{{ craft.gumlet.buildUrl(asset, { width: 300, height: 300 }) }}" alt="{{ asset.title }}" />

{# With Gumlet-specific parameters #}
<img src="{{ craft.gumlet.buildUrl(asset, { width: 300, height: 300 }, { blur: 10 }) }}" alt="{{ asset.title }}" />

Method 3: Native Asset Transforms

If the transformer is active, use Craft's native methods:

{% do asset.setTransform({ width: 300, height: 300 }) %}
<img src="{{ asset.url }}" alt="{{ asset.title }}" />

Method 4: Direct Transformation Array Support

You can now also pass a transformation array directly to getUrl, getWidth, and getHeight:

{% set thumb = {
  mode: 'crop',
  width: 100,
  height: 100,
  quality: 75,
  position: 'top-center'
} %}

<img
  src="{{ asset.getUrl(thumb) }}"
  width="{{ asset.getWidth(thumb) }}"
  height="{{ asset.getHeight(thumb) }}">

This works for both standard named transforms and custom arrays, and will always generate a Gumlet URL.

Note: The automatic transformer may not always be active depending on your Craft CMS configuration. Using gumletUrl() or craft.gumlet.buildUrl() is more reliable.

Supported Transform Parameters

Standard Craft CMS Parameters

• width - Image width
• height - Image height
• quality - Image quality (1-100)
• format - Image format (jpg, png, webp, avif, etc.)

Additional Gumlet Parameters

Pass Gumlet-specific parameters as the third argument:

• blur - Apply blur effect (0-100)
• brightness - Adjust brightness (-100 to 100)
• contrast - Adjust contrast (-100 to 100)
• saturation - Adjust saturation (-100 to 100)
• sharpen - Sharpen the image (0-100)
• rotate - Rotate image (degrees)
• flip - Flip image ('h' for horizontal, 'v' for vertical)
• watermark - Add watermark
• text - Add text overlay

For a complete list, see the Gumlet Image Transformation API documentation.

Configuration Options

All configuration is done via config/gumlet-imagetransformer.php:

return [
    // Your Gumlet domain (required)
    'gumletDomain' => 'your-domain.gumlet.io',
    
    // Enable/disable Gumlet transforms
    'enabled' => true,
    
    // Default quality for images (1-100)
    'defaultQuality' => 80,
    
    // Default format (auto, webp, avif, jpg, png, etc.)
    'defaultFormat' => 'auto',
    
    // Enable automatic format selection
    'autoFormat' => true,
];

How It Works

1. The plugin replaces Craft's default image transformer with Gumlet's transformer
2. When you request an image transform, it generates a Gumlet URL with query parameters
3. Gumlet processes the image on-the-fly and serves the optimized version
4. All transforms are cached by Gumlet's CDN for optimal performance

Benefits

• Performance: Images are served from Gumlet's global CDN
• Optimization: Automatic format selection (WebP, AVIF) based on browser support
• Flexibility: Access to Gumlet's full transformation API
• Cost-Effective: No need to store multiple image sizes on your server
• PDF Support: Transform PDF files into images on-the-fly

Support

• Documentation: GitHub Repository
• Issues: GitHub Issues
• Developer: Anshul Bansal

License

This plugin is licensed under the MIT License.

Changelog

See CHANGELOG.md for a complete list of changes.

---

Note: This plugin uses Gumlet's standard short parameter names (w for width, h for height, q for quality, f for format) as per Gumlet's image transformation API.