webp-convert: ten ways to make WebP from PHP, chosen automatically

Ten conversion methods, and the library picks one for you

webp-convert enables WebP conversion with PHP, and the headline feature is that it supports an abundance of methods and automatically selects the most capable of these that is available on the system.

The list is worth reading in full because it maps onto what real hosting environments provide. cwebp is the reference binary, executed using an exec call. vips is used through the Vips PHP extension. imagick and gmagick are the two ImageMagick PHP extensions, and imagemagick and graphicsmagick are the corresponding command line binaries, also executed with exec. ffmpeg is another exec-based route. wpc is the WebPConvert Cloud Service, an open source webp converter for PHP based on this library. ewww is the ewww cloud converter, which is described as 1 USD startup and then free webp conversion. And gd, the Gd PHP extension, is the fallback that nearly every PHP host has.

The ordering of that list is telling. The binaries and the heavier extensions come first, and gd comes last, which is the right priority because gd is the weakest of the options but also the most ubiquitous.

The practical payoff is that the same code runs on a workstation with cwebp installed and on a shared host with only gd, without the application having to know which one it got. That is the problem this library solves, and it is a real one, because WebP support in the PHP ecosystem has been scattered across extensions, binaries and hosted services for years.

The library is MIT licensed, published on Packagist as rosell-dk/webp-convert, with the primary language PHP.

The convert call, and where the options documentation lives

Installation is a single Composer requirement:

composer require rosell-dk/webp-convert

And the minimal conversion example is short enough to be the whole API surface for most use cases:

// Initialise your autoloader (this example is using Composer)
require 'vendor/autoload.php';

use WebPConvert\WebPConvert;

$source = __DIR__ . '/logo.jpg';
$destination = $source . '.webp';
$options = [];
WebPConvert::convert($source, $destination, $options);

The three arguments are the source path, the destination path and an options array, and in the minimal case that array is empty. That is the design: the library works without configuration and the options are there for when you need them.

The documentation makes a point of the options being extensive rather than showing them inline. The introduction for converting is described as a must-read and is the linked document in docs/v2.0/converting/introduction-for-converting.md, and there is a separate migrating-to-2.0 document for anyone coming from version 1.3.9.

The version split is visible in the repository itself. There are separate composer manifests, composer-php56.json and composer-php72.json, alongside the main composer.json, which is how the library supports older PHP installs without compromising the modern one. The tests have the same shape, with phpunit-41.xml.dist, phpunit.xml.dist and phpunit-with-coverage.xml.dist, and there is a .travis.yml plus a GitHub Actions workflow for the build.

Serving converted images, and the caching decisions that decide whether it is worth it

The second method is the one that turns this from a batch tool into a web feature.

WebPConvert::serveConverted tries to serve a converted image. If there already is an image at the destination, it will take that, unless the original is newer or smaller. If the method cannot serve a converted image, it will serve the original image, a 404, or whatever the fail option is set to. It also adds X-WebP-Convert-Log headers, which provides insight into what happened.

The logic is worth pausing on, because it is where the real engineering is. A converted file on disk is a cache, and a cache that is never invalidated is a bug waiting to happen. The rule here, original newer or original smaller, means a regenerated source file is picked up automatically, and a smaller replacement is preferred, which covers the case where a source has been optimised since the conversion ran.

The 2.0 example shows the option structure:

require 'vendor/autoload.php';
use WebPConvert\WebPConvert;

$source = __DIR__ . '/logo.jpg';
$destination = $source . '.webp';

WebPConvert::serveConverted($source, $destination, [
    'fail' => 'original',     // If failure, serve the original image (source). Other options include 'throw', '404' and 'report'
    //'show-report' => true,  // Generates a report instead of serving an image

    'serve-image' => [
        'headers' => [
            'cache-control' => true,
            'vary-accept' => true,
            // other headers can be toggled...
        ],
        'cache-control-header' => 'max-age=2',
    ],

    'convert' => [
        // all convert option can be entered here (ie "quality")
    ],
]);

Two of those settings decide whether the feature behaves well in production. The vary-accept header is what makes the same URL serve different bytes to different browsers, since a browser without WebP support must not receive WebP, and without Vary: Accept the cache in front of your application will serve the wrong image to the wrong client. The cache-control-header sets the caching policy, and the example uses a very short max-age=2, which suits an on-demand setup where the conversion happens during the request and the cached artefact is disposable.

The fail option is the safety net, and the alternatives are listed in the comment: original, throw, 404 and report. Serving the original on failure is the forgiving choice, and throw is the one that surfaces the problem in your logs rather than hiding it.

What the release history tells you about the maintenance pattern

The release tags are a useful signal about how the project is maintained, because the release notes are unusually specific about what changed.

Version 2.9.5, published on 2026-06-18, is described as fixing deprecated PHP features nicely, preventing warnings, while still using them on older PHP versions. That is a careful kind of fix, because the goal was not to drop support for older PHP but to stop the deprecation warnings on newer versions without breaking the older ones, which is why the repository carries the separate composer manifests for PHP 5.6 and 7.2 alongside the main one.

Version 2.9.4, published the same day earlier, strengthened security for the WPC cloud converter. The WPC option is the WebPConvert Cloud Service, one of the ten conversion methods, and it is the one that sends your images to another machine, so hardening the code that talks to it is a sensible priority.

Between those two and the 2.9.3 release in April 2024 there is a long gap, which suggests releases happen when there is something worth releasing rather than on a schedule.

The last push to the repository was on 2026-06-18, the same day as the newest tag, and the repository is not archived. The project has no GitHub releases listed beyond the tags, and the badge row points to a Packagist version badge, a build status badge for a GitHub Actions workflow, a coverage badge, and monthly download counts.

WebP on demand, and the CMS plugins built on this engine

The library can be used to create a WebP On Demand solution, which automatically serves WebP images instead of jpeg or png for browsers that support WebP. The README points at a tutorial for that, and notes in passing that the tutorial has not been updated for 2.0 yet.

That gap between the 1.3 documentation and the 2.0 code is worth noting when you evaluate the project. The two must-read introductions and the migrating-to-2.0 document are all in docs/v2.0, and the older ones are kept under docs/v1.3, so the documentation is all there, but the webp-on-demand tutorial is still written against the older version. Anyone setting that up for the first time should expect to translate the options structure themselves.

What is more striking is the list of projects built on this engine. The library is used as the engine to provide WebP conversions to a handful of CMS platforms, and the listed ones are WordPress through webp-express, Drupal 7 through Webp-Drupal-7, Contao through contao-webp-bundle, Kirby through kirby-webp, and October CMS through the oc-responsive-images-plugin. The list is ordered by market share, and the author says hopefully it will grow.

Two related projects are also named. webp-convert-cloud-service is a cloud service based on WebPConvert, which is the wpc option in the method list, and webp-convert-concat is the webp-convert library and its dependents as a single PHP file, or two, which is for environments where you cannot use Composer.

The maintainer asks for sponsorship through Patreon and Ko-fi, and the repository has a BACKERS.md file and a list of current backers.

Editorial conclusion

webp-convert suits a PHP application that needs WebP output without being able to require a particular extension on the server, because the automatic selection of the best available method is the feature that makes one configuration work across hosting environments. It does not suit you if you want full control over the conversion, since the method selection is the library's decision and the cloud options send your images to a third party, which is a data protection question rather than a technical one. Before you deploy it, check which methods are actually available on your server, and if you use the ewww or cloud service options, verify that sending your images off the machine is acceptable for what you are converting.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. rosell-dk/webp-convert on GitHub