Download the PHP package shykat199/webpbolt without Composer

WebpBolt — Fast, Modular Image to WebP Converter for PHP

Convert JPG, PNG, GIF and BMP images to WebP in PHP — one file at a time, or an entire directory tree in a single call. Lightweight, zero dependencies, built on PHP's native GD extension.

WebP files are typically 25–35% smaller than JPG and PNG, so converting your images makes websites load faster and improves Core Web Vitals.

Features

• Convert JPG, JPEG, PNG, GIF and BMP to WebP
• Batch mode — convert a whole folder tree, with progress reporting and a dry-run preview
• Resumable — already-converted files are skipped on repeat runs, so it's safe on a cron
• Never makes things worse — output larger than the original is discarded automatically
• Watermarking — stamp text or a logo, nine positions, adjustable opacity
• Modular pipeline — chain transforms (resize, grayscale, watermark, auto-orient)
• Pluggable encoders — add new output formats (AVIF, JPEG, ...)
• Adjustable quality (0–100), preserves PNG transparency
• No external dependencies — pure PHP + GD

Requirements

• PHP 8.1 or higher
• GD extension with WebP support
• ext-exif (optional) — only needed for the AutoOrient transform
• FreeType support in GD (optional) — only needed for .ttf watermark fonts

Check WebP support:

Installation

Quick start

Convert one image

WebpBolt is a thin fluent wrapper. The underlying ImageProcessor API is unchanged and still available if you prefer it:

Convert a whole folder

That's the common case. Everything below is for when you need more control.

Batch conversion

Preview before you commit

On a production folder, always dry-run first. It walks the tree and counts everything without writing a single file:

Watch the progress

Pass a callback to get told about each file as it's handled. Add countFirst() if you want a real total in the output — it costs one extra pass over the folder:

Resize everything while converting

Pass a pre-configured ImageProcessor and its transforms apply to every file in the batch:

Convert in place

Leave the destination unset and each .webp is written next to its original:

Handle failures

The batch never stops on a bad file. Errors are collected and handed back:

Run it from cron

Repeat runs are cheap — the skip check reads file timestamps and never decodes an image, so an already-converted tree of 40,000 files finishes in seconds:

All batch options

Turn skipExisting off to force a full rebuild — for example after changing the quality setting:

Reading the result

run() returns a BatchResult:

Single-image pipeline

Chain transforms, then encode

Resize fits the image inside the given box while keeping its aspect ratio, and only ever shrinks — passing a box larger than the image leaves it untouched.

Note that transforms stay attached to the processor, so reusing an instance applies them again to the next file. That's exactly what you want when feeding it to BatchProcessor; create a fresh ImageProcessor when you don't.

Watermarking

Stamp text or a logo onto an image. Two named constructors, then chain only the things you want to change — every option has a working default.

That's a complete watermark: white text, bottom-right, 60% opacity, 20px margin.

Text watermarks

Without font() this falls back to GD's built-in bitmap font, which needs no asset files but is small and blocky. For anything customer-facing, pass a real .ttf.

color() takes '#ffffff', 'fff', 'ffffff' or [255, 255, 255].

Image watermarks

Use a PNG with a transparent background. scale() is a fraction of the base image width, not a pixel size — 0.2 means the logo is 20% as wide as the photo. That keeps it proportionate whether you're stamping a thumbnail or a 4000px original; a fixed pixel width would be enormous on one and invisible on the other.

Positions

position() accepts the Position enum or its string value:

The enum gives you IDE autocompletion and turns a typo into an error instead of a mis-placed logo. Strings are there for config-driven setups.

All watermark options

Order matters

Add the watermark after the resize:

Watermarking first means the logo gets shrunk along with the photo and comes out tiny and blurry. Transforms run in the order you add them, and nothing enforces this for you.

Watermarking a whole folder

Pass a configured processor to BatchProcessor and every file gets the same treatment:

Architecture

Add a new transform

One file in src/Transforms/ implementing TransformInterface:

Then use it: ->addTransform(new Watermark('© Me')). No other file changes.

A transform may return a different GdImage than it was given — Resize does, because it has to build a new canvas. Treat the handle you passed in as invalid once apply() has returned.

Add a new output format

One file in src/Encoders/ implementing EncoderInterface:

It then works everywhere an encoder is accepted, batch included:

Quality guide

Notes and limitations

• Animated GIFs lose everything but the first frame. GD can't read the rest.
• EXIF orientation is not handled by default. Photos straight off a phone come out rotated unless you add the AutoOrient transform, which reads the EXIF flag and rotates for you. Add it first in the chain.
• Metadata is not preserved — EXIF, ICC colour profiles and copyright tags are dropped by GD. Good for file size and privacy, bad if you need them.
• Memory: GD decodes to roughly width × height × 4 bytes. Batch mode refuses oversized images rather than letting PHP die with an uncatchable fatal, but a single very large image can still exceed memory_limit on the transform step.

License

MIT

Laravel

The package auto-registers when installed in a Laravel app. Publish the config:

Set your defaults once in config/webpbolt.php:

Then convert a folder from the command line:

An ImageProcessor pre-configured from that config is bound in the container, so injecting it anywhere gives you the resize and watermark for free:

Put it on a schedule to catch new uploads. Repeat runs cost one filesystem stat per file, so this is cheap:

Errors

Everything thrown extends WebpBoltException, which extends RuntimeException — so existing catch (RuntimeException) blocks keep working while new code can catch precisely:

BatchProcessor catches these per file and collects them in $result->failed, so one bad image never stops a run.

Testing