jorisnoo / craft-imageboss
ImageBoss image CDN integration for Craft CMS with native transform fallback
Package info
github.com/jorisnoo/craft-imageboss
Type:craft-plugin
pkg:composer/jorisnoo/craft-imageboss
Requires
- php: ^8.3
- craftcms/cms: ^5.0
Requires (Dev)
- mockery/mockery: ^1.6
- pestphp/pest: ^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 06:52:24 UTC
README
ImageBoss integration for Craft CMS with native transform fallback.
Requirements
- PHP 8.4+
- Craft CMS 5
Installation
composer require jorisnoo/craft-imageboss
Copy the config file to config/imageboss.php:
cp vendor/jorisnoo/craft-imageboss/src/config/imageboss.php config/imageboss.php
Configuration
Set your ImageBoss credentials in .env:
IMAGEBOSS_SOURCE=your-source IMAGEBOSS_TOKEN=your-token # optional, for URL signing IMAGEBOSS_API_KEY=your-key # optional, for cache purging
When IMAGEBOSS_SOURCE is not set, the plugin falls back to Craft's native image transforms.
Config Options
| Option | Default | Description |
|---|---|---|
source |
null |
ImageBoss source identifier |
token |
null |
HMAC token for URL signing |
apiKey |
null |
API key for cache purging |
baseUrl |
https://img.imageboss.me |
ImageBoss CDN base URL |
includeVolumeFolder |
false |
Include volume folder name in URL path |
defaultWidth |
1000 |
Default width for url() |
defaultInterval |
200 |
Step size for srcset generation |
presets |
[] |
Named preset configurations |
Presets
The plugin supports two approaches for defining presets: config-based and interface-based.
Option 1: Config-Based Presets
Define presets in config/imageboss.php:
'presets' => [ 'thumbnail' => [ 'min' => 200, // minimum srcset width 'max' => 700, // maximum srcset width 'ratio' => 1, // aspect ratio (optional) 'interval' => 250, // width step (optional) ], 'hero' => [ 'min' => 640, 'max' => 3840, ], 'shareImage' => [ 'min' => 1200, 'max' => 1200, 'ratio' => 1200 / 630, 'format' => 'jpg', // output format (optional) 'quality' => 90, // output quality 1-100 (optional) ], ],
Option 2: Interface-Based Presets
Implement the ImagePreset interface on your enum for self-contained presets:
use Noo\CraftImageboss\concerns\HasImagePresetHelpers; use Noo\CraftImageboss\contracts\ImagePreset; enum Preset: string implements ImagePreset { use HasImagePresetHelpers; case Default = 'default'; case Thumbnail = 'thumbnail'; case Card = 'card'; case Hero = 'hero'; /** * @return array{min: int, max: int, ratio?: float, interval?: int} */ public function config(): array { return match ($this) { self::Default => ['min' => 320, 'max' => 2560], self::Thumbnail => ['min' => 200, 'max' => 700, 'ratio' => 1, 'interval' => 250], self::Card => ['min' => 300, 'max' => 800, 'ratio' => 4 / 5], self::Hero => ['min' => 640, 'max' => 3840], }; } }
The HasImagePresetHelpers trait provides convenience methods:
Preset::Hero->min(); // 640 Preset::Hero->max(); // 3840 Preset::Card->ratio(); // 0.8 Preset::Thumbnail->interval(); // 250
Cache Purging
When IMAGEBOSS_SOURCE and IMAGEBOSS_API_KEY are set, replacing, moving, renaming or deleting an asset queues a purge of the ImageBoss master image and its variants. A path change purges both the original and the new path. Metadata-only saves do not purge. The worker uses Craft’s Guzzle configuration with finite timeouts; connection failures, rate limits and server errors are eligible for up to three attempts. Inspect failed jobs in Craft’s queue manager.
ImageBoss processes purges asynchronously. Purging does not invalidate users’ browser caches or other CDNs; use a new filename when immediate client-side invalidation matters. See the ImageBoss caching docs.
Usage
Twig
The plugin registers the craft.imageboss template variable and Twig filters for site, control panel and console-rendered templates. For the shorthand imageboss used below, add {% set imageboss = craft.imageboss %} to your template.
Fluent API
{# Single URL #} {{ imageboss.from(asset).width(800).url() }} {{ imageboss.from(asset).width(800).ratio(16/9).url() }} {# Responsive srcset with preset #} {{ imageboss.from(asset).preset('hero').srcsetString() }} {# Custom srcset range #} {{ imageboss.from(asset).min(300).max(1200).interval(200).srcsetString() }} {# CDN passthrough (no transform) #} {{ imageboss.from(asset).cdn() }} {{ imageboss.from(asset).cdn({ compression: false }) }} {# Force browser download (standalone or combined with any operation) #} {{ imageboss.from(asset).download(true).url() }} {{ imageboss.from(asset).download('annual-report.pdf').url() }} {{ imageboss.from(asset).width(800).download(true).url() }} {{ imageboss.from(asset).download('annual-report.pdf').cdn() }} {# Animated GIFs (by default only the first frame is processed) #} {{ imageboss.from(asset).width(300).animation().url() }} {{ imageboss.from(asset).width(300).height(300).animation().format('mp4').url() }} {# Placeholder for lazy loading #} {{ imageboss.from(asset).width(800).ratio(16/9).placeholder() }} {{ imageboss.from(asset).preset('card').placeholder('#f0f0f0') }}
Shorthand Methods
{# With preset name #} {{ imageboss.url(asset, 'hero') }} {{ imageboss.srcset(asset, 'hero') }} {{ imageboss.placeholder(asset, 'card') }} {{ imageboss.cdn(asset) }} {{ imageboss.cdn(asset, { compression: false }) }} {# With options array #} {{ imageboss.url(asset, { width: 800, height: 600, format: 'webp', quality: 80 }) }} {{ imageboss.url(asset, { width: 300, animation: true }) }} {{ imageboss.srcset(asset, { min: 300, max: 1200, interval: 200 }) }} {{ imageboss.placeholder(asset, { preset: 'card', color: '#e0e0e0' }) }}
Filters
{{ asset | imageboss_url({ width: 800 }) }}
{{ asset | imageboss_srcset('hero') }}
{{ asset | imageboss_cdn }}
{{ asset | imageboss_placeholder({ color: '#e0e0e0' }) }}
Full Example
{% set result = imageboss.transform(asset, 'hero') %}
<img
src="{{ result.last().url }}"
srcset="{{ result.srcset() }}"
sizes="100vw"
width="{{ result.last().width }}"
{% if result.last().height %}height="{{ result.last().height }}"{% endif %}
alt="{{ asset.title }}"
>
With a placeholder for lazy loading:
<img src="{{ imageboss.placeholder(asset, 'hero') }}" data-srcset="{{ imageboss.srcset(asset, 'hero') }}" data-sizes="auto" alt="{{ asset.title }}" >
PHP
use Noo\CraftImageboss\builders\ImageBossBuilder; // Via the plugin variable $builder = Plugin::$plugin->variable->from($asset); $url = $builder->width(800)->url(); $srcset = $builder->preset('hero')->srcsetString(); $placeholder = $builder->width(800)->ratio(16/9)->placeholder();
Builder Methods
| Method | Description |
|---|---|
width(int) |
Set image width |
height(int) |
Set image height |
ratio(float) |
Set aspect ratio (width/height) |
min(int) |
Minimum width for srcset |
max(int) |
Maximum width for srcset |
interval(int) |
Width step for srcset |
format(string) |
Output format override |
quality(int) |
Output quality 1-100 |
animation(bool) |
Preserve animation for animated GIFs. By default ImageBoss only processes the first frame. Combine with format('mp4') to convert to video. |
download(bool|string) |
Force browser download. true keeps the original filename, a string sets a custom one. |
preset(string|BackedEnum|ImagePreset) |
Apply preset configuration |
url() |
Generate single URL |
srcset() |
Generate srcset array |
srcsetString() |
Generate srcset string |
transform() |
Get TransformResult with first(), last(), all() |
cdn(array $options = []) |
Generate passthrough URL via ImageBoss cdn operation (no transform). Falls back to the asset's native URL when no source is configured. Pass ['compression' => false] to disable ImageBoss compression. |
placeholder(?string $color) |
Generate SVG data-URI placeholder |
aspectRatio() |
Get resolved aspect ratio |
All setter methods accept null safely and return $this for chaining.
For a single URL, width is chosen from explicit width, then max, min, and finally defaultWidth. For a srcset, explicit width fills in missing range bounds; width and height together preserve the crop ratio across candidates. Each range contains at most 50 widths and includes its maximum. Nonpositive preset dimensions, ratios and intervals are ignored.
Asset path segments are percent-encoded before URL signing. Custom download names are encoded as a single option value; path separators are replaced with hyphens. Placeholder backgrounds accept named colors, hex and numeric RGB/HSL colors; other expressions are omitted.
Example Output
url() returns a single URL:
https://img.imageboss.me/your-source/width/800/format:auto/assets/image.jpg
srcsetString() returns a comma-separated srcset string:
https://img.imageboss.me/.../width/640/... 640w, https://img.imageboss.me/.../width/1280/... 1280w
When an asset has a focal point set, it's automatically included in the URL:
https://img.imageboss.me/your-source/cover/800x450/fp-x:0.25,fp-y:0.75,format:auto/assets/image.jpg
Assets without a focal point default to center (fp-x:0.5,fp-y:0.5) so cover crops stay centred instead of falling back to ImageBoss's smart-crop.
Features
- Responsive srcset generation with configurable width ranges and intervals
- Focal point support from Craft asset focal points
- URL signing with HMAC-SHA256
- SVG placeholder generation for lazy loading
- Named presets via config or typed enums
- Automatic fallback to Craft's native transforms
License
MIT
Maintainer releases
See RELEASING.md for versioning, changelog entries and the release command.