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
• 🛡️ 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

Basic Usage

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

{# Specify fit mode and quality #}
{% set img = record.product_image|webp_thumbnail(1920, 1080, 'c', 85) %}

Fit Modes

{# 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:

<picture>
    <source type="image/webp" srcset="{{ record.image|webp_thumbnail(1920, 1080, 'c', 85) }}">
    <source type="image/jpeg" srcset="{{ record.image|thumbnail(1920, 1080, fit='c', quality=85) }}">
    <img src="{{ record.image|thumbnail(1920, 1080) }}" alt="Responsive image">
</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

1. Extract image – Gets the image path from Bolt field types (ImageField, Image, FieldTranslation)
2. Calculate dimensions – Processes width/height parameters and fit mode
3. Generate filename – Creates unique filename with hash based on parameters
4. Check cache – Returns existing WebP file if it exists
5. Convert – Converts original image directly to WebP using GD library
6. Save – Stores WebP file in the public directory (usually public/thumbs)
7. Return – Returns relative URL path to the WebP image

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.