PHPackages                             enjoydev/bolt-webp - 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. enjoydev/bolt-webp

ActiveBolt-extension[Image & Media](/categories/media)

enjoydev/bolt-webp
==================

Bolt CMS extension for converting images to WebP format with customizable thumbnails, fit modes, and quality settings.

v1.0.1(today)02↑2900%MITPHPPHP >=7.4

Since Jun 18Pushed todayCompare

[ Source](https://github.com/5ulo/bolt-webp)[ Packagist](https://packagist.org/packages/enjoydev/bolt-webp)[ RSS](/packages/enjoydev-bolt-webp/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (2)Versions (3)Used By (0)

Bolt WebP Converter
===================

[](#bolt-webp-converter)

[![Bolt CMS](https://camo.githubusercontent.com/b8dbf928c7cc762400201f44424ce846d5b13bc8ee658b76abc4873184e220ae/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f426f6c74253230434d532d362e302d677265656e)](https://boltcms.io)[![PHP](https://camo.githubusercontent.com/2f6f9af2e917cbf5786673e8e4ed8d0d9b29be6131327a992063e69136a93411/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e302532422d626c7565)](https://php.net)[![License](https://camo.githubusercontent.com/8174925d009b42074d50ab5cc7e29fcb1aa613b0d9cb2e43097697a40cf90fa4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f77)](https://opensource.org/licenses/MIT)

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

Features
--------

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

[](#requirements)

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

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

[](#installation)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require enjoydev/bolt-webp
```

### 2. Clear the cache

[](#2-clear-the-cache)

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

```
bin/console cache:clear
```

### 3. Verify installation

[](#3-verify-installation)

Ensure the extension is loaded:

```
bin/console extensions:list
```

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

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

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

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

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

```

### Accessing Dimensions & Metadata (v1.0.1+)

[](#accessing-dimensions--metadata-v101)

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) %}

```

### Fit Modes

[](#fit-modes)

ModeParameterDescriptionMax (default)`'m'` or `'max'`Fits within bounds without upscaling smaller imagesCrop`'c'`Resizes to fill dimensions and crops excess dataContain`'n'` or `'contain'`Fits image within bounds, maintains aspect ratioFill`'f'` or `'fill'`Fits within bounds, fills empty space with white backgroundStretch`'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

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

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

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

```

### Advanced Example (Multiple Sizes)

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

```

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

[](#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 Object** – Returns `WebPImage` object containing path, width, height, and alt text

File Naming Convention
----------------------

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

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

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

[](#troubleshooting)

### WebP files not being generated

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

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

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

[](#images-not-showing-up)

Check the Bolt logs for conversion errors:

```
tail -f var/log/prod.log
```

Support
-------

[](#support)

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

- 🐛 **Report a bug:** [Create an Issue](https://github.com/5ulo/bolt-webp/issues)
- 💡 **Feature request:** [Create an Issue](https://github.com/5ulo/bolt-webp/issues)
- 📖 **Bolt Documentation:** [docs.boltcms.io](https://docs.boltcms.io)

License
-------

[](#license)

This extension is released under the MIT License.

Credits
-------

[](#credits)

Developed by [EnjoyDev](https://github.com/5ulo) for the Bolt CMS community.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance100

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

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

Every ~0 days

Total

2

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4980919?v=4)[EnjoyDev](/maintainers/5ulo)[@5ulo](https://github.com/5ulo)

---

Top Contributors

[![5ulo](https://avatars.githubusercontent.com/u/4980919?v=4)](https://github.com/5ulo "5ulo (3 commits)")

---

Tags

thumbnailimagegdcmsextensionWebpbolt

### Embed Badge

![Health badge](/badges/enjoydev-bolt-webp/health.svg)

```
[![Health](https://phpackages.com/badges/enjoydev-bolt-webp/health.svg)](https://phpackages.com/packages/enjoydev-bolt-webp)
```

###  Alternatives

[intervention/image

PHP Image Processing

14.3k203.8M2.5k](/packages/intervention-image)[james-heinrich/phpthumb

The PHP thumbnail generator

317545.2k18](/packages/james-heinrich-phpthumb)[intervention/image-symfony

Symfony Integration of Intervention Image

1084.3k](/packages/intervention-image-symfony)[somehow-digital/typo3-media-processing

Media Processing

121.2k](/packages/somehow-digital-typo3-media-processing)

PHPackages © 2026

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