README

A Bolt CMS extension that automatically converts images to WebP format with customizable thumbnails, fit modes, and quality settings.

Features

🚀 Direct conversion – Converts original images directly to WebP (no intermediate compression artifacts)
📐 All fit modes – Supports crop, contain, max, fill, and stretch modes
🔍 Smart sizing – Handles width/height parameters intelligently (single dimension, both, or none)
🎨 Transparency support – Preserves alpha channels for PNG and GIF images
📁 Custom paths – Define your own output directories
⚡ Caching – Generates WebP files only once, reuses them on subsequent requests
📊 Object Interface – Returns a rich object with path, dimensions, and Alt text (v1.0.1+)
🛡️ Graceful fallback – Returns original image path if conversion fails

Requirements

PHP 8.0 or higher
Bolt CMS 6.0
GD extension with WebP support

Installation

1. Install via Composer

composer require enjoydev/bolt-webp

2. Clear the cache

After installation, clear the cache to register the new Twig filter:

bin/console cache:clear

3. Verify installation

Ensure the extension is loaded:

bin/console extensions:list

You should see EnjoyDev\BoltWebp\Extension in the list.

Configuration

This extension works out of the box with sensible defaults. No configuration file is required. If you need to adjust quality or default paths, you can do so directly in your Twig templates.

Usage

The webp_thumbnail filter returns a WebPImage object. This object contains the path, dimensions, and metadata, but can be used as a string for backward compatibility.

Basic Usage

{# Convert with default settings (crop fit, 85% quality) #}
{% set img = record.product_image|webp_thumbnail(1920, 1080) %}

{# Use directly in src attribute (Object is cast to string) #}
<img src="{{ img }}" alt="Product image">

Accessing Dimensions & Metadata (v1.0.1+)

Because the filter returns an object, you can easily access the width, height, and Alt text of the generated WebP image.

{% set img = record.product_image|webp_thumbnail(1920, 1080, 'c', 85) %}

<img 
    src="{{ img.path }}" 
    width="{{ img.width }}" 
    height="{{ img.height }}" 
    alt="{{ img.alt|default('My default alt text') }}"
>

Fit Modes

Mode	Parameter	Description
Max (default)	`'m'` or `'max'`	Fits within bounds without upscaling smaller images
Crop	`'c'`	Resizes to fill dimensions and crops excess data
Contain	`'n'` or `'contain'`	Fits image within bounds, maintains aspect ratio
Fill	`'f'` or `'fill'`	Fits within bounds, fills empty space with white background
Stretch	`'s'` or `'stretch'`	Stretches exactly to dimensions (distorts image)

{# Different fit modes examples #}
{% set crop_img = record.image|webp_thumbnail(800, 600, 'c', 85) %}
{% set contain_img = record.image|webp_thumbnail(800, 600, 'n', 85) %}
{% set max_img = record.image|webp_thumbnail(800, 600, 'm', 85) %}
{% set fill_img = record.image|webp_thumbnail(800, 600, 'f', 85) %}
{% set stretch_img = record.image|webp_thumbnail(800, 600, 's', 85) %}

Single Dimension

If you specify only one dimension, the other will be calculated automatically to maintain aspect ratio:

{# Width only (height calculated automatically) #}
{% set img = record.image|webp_thumbnail(800, 0, 'c', 85) %}

{# Height only (width calculated automatically) #}
{% set img = record.image|webp_thumbnail(0, 600, 'c', 85) %}

Custom Output Directory

You can specify a custom directory for the WebP files:

{# In /thumbs/ directory #}
{% set img = record.product_image|webp_thumbnail(1920, 1080, 'c', 85, 'food') %}
{# Result: /thumbs/food/soup-a1b2c3d4.webp #}

{# Custom path with subdirectories #}
{% set img = record.product_image|webp_thumbnail(1920, 1080, 'c', 85, 'uploads/products/featured') %}
{# Result: /uploads/products/featured/soup-a1b2c3d4.webp #}

Responsive Images (Picture Element)

This is the recommended way to use WebP for better performance. You can still use the object directly in srcset.

{% set webp = record.image|webp_thumbnail(1920, 1080, 'c', 85) %}

<picture>
    <source type="image/webp" srcset="{{ webp.path }}">
    <source type="image/jpeg" srcset="{{ record.image|thumbnail(1920, 1080, fit='c', quality=85) }}">
    <img src="{{ record.image|thumbnail(1920, 1080) }}" alt="{{ webp.alt }}">
</picture>

Advanced Example (Multiple Sizes)

{% set img_mobile = record.image|webp_thumbnail(400, 600, 'c', 85, 'images/mobile') %}
{% set img_tablet = record.image|webp_thumbnail(768, 1024, 'c', 85, 'images/tablet') %}
{% set img_desktop = record.image|webp_thumbnail(1920, 1080, 'c', 85, 'images/desktop') %}

<picture>
    <source media="(max-width: 480px)" type="image/webp" srcset="{{ img_mobile }}">
    <source media="(max-width: 1024px)" type="image/webp" srcset="{{ img_tablet }}">
    <source type="image/webp" srcset="{{ img_desktop }}">
    <img src="{{ record.image|thumbnail(1920, 1080) }}" alt="Product image">
</picture>

How It Works

Extract image – Gets the image path from Bolt field types (ImageField, Image, FieldTranslation)
Calculate dimensions – Processes width/height parameters and fit mode
Generate filename – Creates unique filename with hash based on parameters
Check cache – Returns existing WebP file if it exists
Convert – Converts original image directly to WebP using GD library
Save – Stores WebP file in the public directory (usually public/thumbs)
Return Object – Returns WebPImage object containing path, width, height, and alt text

File Naming Convention

The extension generates filenames in this format:

original_filename-[hash].webp

Where hash is an 8-character MD5 hash based on dimensions, fit mode, quality, and original filename.

Example:

Original: soup.png
Output: soup-a1b2c3d4.webp

Maintenance

WebP files are generated once and stored permanently on your server. If you frequently update images or change dimensions, you might want to clean up old files.

Cleaning up old files

You can remove unused WebP files by deleting the contents of the public/thumbs directory (or your custom directories) via FTP or a command line tool.

Example command to remove all generated thumbnails:

rm -rf public/thumbs/*

Note: Be careful not to delete folders that contain manually uploaded files if you use overlapping paths.

Troubleshooting

WebP files not being generated

Ensure GD is installed with WebP support:

php -i | grep -i webp

You should see WebP Support => enabled.

Allowed memory size exhausted

If you are processing very large images (e.g., 4000px+), PHP might run out of memory. Increase the memory limit in your php.ini:

memory_limit = 256M

Or temporarily in your script (not recommended for production):

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

Permission issues

Ensure the web server has write permissions to the output directories (usually public/thumbs):

chmod -R 775 public/thumbs

Images not showing up

Check the Bolt logs for conversion errors:

tail -f var/log/prod.log

Support

Found a bug or have a feature request? Please report it on the GitHub issue tracker.

🐛 Report a bug: Create an Issue
💡 Feature request: Create an Issue
📖 Bolt Documentation: docs.boltcms.io

License

This extension is released under the MIT License.

Credits

Developed by EnjoyDev for the Bolt CMS community.

enjoydev / bolt-webp

Maintainers

Package info

Statistics

Security