Download the PHP package nikocodes/picowebp without Composer

PicoWebP

PicoWebP converts PNGs, baseline JPEGs, BMPs and raw RGB pixels to WebP using PHP. The encoder writes the VP8 bitstream itself, and the PNG, JPEG and BMP readers ship with the package. No GD, Imagick, cwebp or libwebp is required for those inputs.

This is for the host where you need WebP conversion but cannot install an image extension or a command-line encoder. It keeps transparency and ICC colour profiles, works from PHP or the command line, and includes a way to split encoding into smaller jobs.

The trade-off is CPU time. With the default settings, encoding a roughly 1 MP image took 25 seconds on the benchmark machine; a 12 MP image took several minutes. Use a native encoder when one is available, and run PicoWebP in a background queue. The timings below show what that means in practice.

Resumable encoding

Project website · Packagist

Install

You need PHP 8.1 or newer and ext-zlib.

The package is available on Packagist.

GD is optional. PicoWebP can use it to read images faster when it is installed, and it is required for progressive JPEG input or re-encoding an existing WebP. WebP encoding itself always runs in PHP.

Quick start

Put this script and photo.jpg in your application's root directory:

Quality runs from 0 to 100. The same code works with a PNG, including one with transparency. Colour is encoded lossily; the alpha plane is encoded losslessly.

To prefer the bundled readers even when GD is installed, set ImageInput::$preferBundled = true before reading the file. To disable GD entirely, set ImageInput::$gdAvailable = false.

Starting with raw pixels

The encoder accepts a packed RGB string: three bytes per pixel, red then green then blue, ordered from the top-left pixel across each row. For example, this writes a small red square:

For transparency, assign a packed alpha string to $encoder->alphaPlane: one byte per pixel, from 0 (transparent) to 255 (opaque). An RGB buffer must contain exactly width × height × 3 bytes; an alpha buffer must contain width × height bytes. Each dimension must be between 1 and 16,383 pixels. Those format limits are much higher than sensible limits for a PHP queue: set your own megapixel cap.

See examples/encode.php for a runnable example.

Command line

Composer installs the command in vendor/bin:

From a checkout of this repository, use bin/picowebp instead.

Despite its name, --alpha=flatten simply drops the alpha plane. It does not composite the image onto a chosen background.

The CLI exits with 0 after an encode, 1 for an error, 3 when --alpha=fail rejects input, and 4 when it skips an existing WebP. Check the exit code before marking a queue job as converted.

Supported inputs

On a host without GD, progressive JPEGs need to be converted to baseline JPEG or decoded to raw RGB elsewhere first. The bundled reader reports unsupported JPEG variants rather than attempting to decode them as baseline.

BMP files always use the bundled reader, so decoding behaves the same on hosts with and without GD. It reads OS/2 core headers and Windows BITMAPINFOHEADER and V2–V5 headers, including palettes, channel masks and bottom-up or top-down rows. Other header formats and BMPs containing JPEG or PNG payloads are not supported.

For 16-bit BMPs, PicoWebP scales the 5- or 6-bit colour channels to eight bits using rounding. Another decoder may produce a value one step higher or lower for some colours.

Transparency and metadata

The bundled PNG reader retains all eight bits of alpha, including palette transparency and tRNS. The encoder stores that alpha losslessly in an ALPH chunk alongside the lossy colour data. Fully opaque images do not need an alpha chunk. GD has lower alpha precision, so use the bundled reader when preserving the source alpha exactly matters.

BMP transparency comes from an alpha mask in the header or the mask block that follows it. A declared alpha channel is preserved, including an image where every pixel is fully transparent. A 32-bit BI_RGB file uses the opaque BGRX layout, so its fourth byte and any unused channel masks are ignored.

ICC profiles from PNG iCCP and JPEG APP2 chunks, and embedded profiles from BMP V5 headers, are copied into the output. This preserves the profile; it does not make the colour encoding lossless.

EXIF metadata is not copied, and orientation tags are not applied. Rotate or mirror photos as needed before passing them to PicoWebP.

Existing WebP files

PicoWebP skips WebP input by default. It checks the file contents, so a WebP named photo.jpg is still skipped, while a PNG named photo.webp can still be converted.

In PHP, catch SkippedInput separately from conversion failures:

SkippedInput extends RuntimeException. You can check a file in advance with ImageInput::isWebp($file).

To allow re-encoding, set ImageInput::$skipWebp = false or pass --reencode-webp. GD must be available to read it. A normal CLI skip leaves the destination untouched and returns exit code 4.

File sizes

These are the project's recorded results for ten real images at quality 80 with the encoder defaults. The libwebp column uses its default effort. The same quality number does not mean the same visual quality across encoders, so smaller output alone does not establish better compression.

PicoWebP produced smaller files on some photos and phone captures, and larger files on some artwork and UI captures. The recorded real-photo results also had lower PSNR, by 0.2–1.6 dB. These results describe this small sample, not every image you might convert.

Check appearance and file size before replacing an original. For transparent images, raw RGB PSNR can also be misleading because fully transparent pixels may contain different, invisible colour values.

Generated fixtures

These images were generated from gradients, noise and graphics during development. They are useful for comparing encoder changes, but results on them won't necessarily carry over to photographs. Like the real-image results above, these were recorded at quality 80 with the default settings.

The recorded output sizes were 1.7–5.8% below libwebp up to about 3 MP and 2.4–4.1% below it at 12 MP, with PSNR 0.05–0.25 dB lower. As with the real images, the smaller files came with a quality difference.

At maximum effort (cwebp -m6), libwebp reduced its output size by 1.4–5.8%. On the 12 MP fixtures, its JPEG result was 1.1% smaller than PicoWebP's and its PNG result was 1.4% larger; on the smaller fixtures, its files remained 0.5–7% larger. The recorded 12 MP encode took 2.2 seconds with cwebp -m6, compared with about 377 seconds in PHP.

Speed and memory

The measurements below were recorded on one macOS laptop using PHP 8.4, quality 80, the default encoder settings and one process. They are useful for planning a queue, but they are not promises about another machine or host.

Encoding only, after the source has been decoded to RGB:

Reading only, before encoding starts. The table records results for a 4000×3000 photo re-saved in each format, with a range for PNG filter layouts. The phone screenshot discussed below is a separate sample:

The encoder receives decoded pixels, so inputs with the same RGB, alpha and ICC data produce the same output at the same settings. The same 800×600 photo saved as BMP, PNG and raw RGB produced byte-identical WebP output — 42,814 bytes from all three — where libwebp wrote 42,952.

The three BMP rows use the same source image in different storage layouts. Reducing it to 16-bit colour or an 8-bit palette can change the decoded pixels. The 24-bit reader mainly reorders BGR bytes into RGB. The 16-bit path took about seven times as long per pixel in this sample, since each channel has to be unpacked and scaled to a byte; RLE took about two and a half times as long. An uncompressed 24-bit BMP also needs roughly three bytes per pixel: a 12 MP file is about 34 MiB, and the reader holds that alongside the decoded RGB while it works.

PNG read time depends heavily on the filters chosen by the writer, as well as the compressed data. In a separate screenshot sample, rows using None read at 19 ms/MP (about 0.02 s/MP); the photo PNG using Paeth read at 0.8 s/MP, about forty times slower. The screenshot result is not the lower bound in the table. Time a file from your own source before planning a queue around PNG input.

In the bundled JPEG reader, the recorded CPU breakdown was 53% inverse DCT, 27% upsampling and YCbCr-to-RGB conversion, 6% block storage and 13% Huffman decoding. For comparison, libjpeg-turbo decoded the 12 MP image in 0.11 s; the GD path also spends time copying pixels into the RGB buffer.

Adding the listed 12 MP JPEG read and encode times gives about 398 seconds with the bundled reader. This is a sum of the separate measurements. GD speeds up the reading stage, but the PHP encoding work remains. Native libwebp is substantially faster.

Keep conversions out of page requests. Limit input dimensions, allow for the decoded image's memory use, and pace queue jobs to fit your host's CPU allowance.

Adjusting the work per image

The defaults enable 4×4 prediction, coefficient-probability adaptation, rate-distortion mode selection and macroblock skip flags. Trellis quantisation is off by default.

The CLI exposes --no-bpred, --no-adapt-probs, --no-rd, --prune=N, --rd-lambda=N, --trellis and --no-skip. The corresponding encoder properties include enableBPred, adaptProbs, enableRd, rdPruneCandidates, rdLambda, enableTrellis and enableSkipFlags.

The following measurements use the same two images for each setting. File-size changes are relative to the defaults, with synthetic-image results first and real-image results second. Changing the search also changes quality, so compare the resulting images as well as the numbers.

Reducing the search can save CPU, but also changes output size and quality. Test with your own images before changing the defaults. Enabling trellis adds work and can change detail as well as file size; it is not a free quality improvement.

Resumable encoding

The resumable path stages image planes on disk with PlaneStore, then processes bands of macroblock rows. beginBand(), encodeRowRange() and compactReconWindow() handle the bands; finishFrame() completes the file. exportState() and importState() let an application carry the encoder state between invocations.

See examples/chunked-queue.php for the sequence. It runs the stages in one process and compares the result with a single-shot encode. A real queue needs to persist the state and schedule the next band itself.

This makes the work resumable, not faster. The demonstrated path includes staging, a statistics pass and an encoding pass, and uses about twice the CPU of a single-shot encode. The initial staging step still needs the decoded image in memory, so it does not remove the need for an input-size limit.

For the recorded 3 MP image, the resumable loop held 23 MB compared with a 24 MB peak for the single-shot encoder. About 79 seconds of encoding became 158 seconds of work across the two passes. The benefit is being able to pause between bands and continue later.

Tests

From a checkout of this repository:

Tests cover the bitstream, alpha and ICC chunks, image readers, CLI results, malformed input and resumable encoding. When dwebp is available on PATH, additional checks decode the output with libwebp. These external tools are for validation; they are not encoding dependencies.

Scope and license

PicoWebP writes lossy VP8 WebP images. It does not provide a general-purpose lossless WebP encoder. PicoWebP\Spike\Vp8lEncoder is an internal helper for alpha channels.

Release changes are in MIT license.