Serve autogenerated WebP images instead of jpeg/png to browsers that supports WebP

1.0.0 2018-09-04 06:49 UTC

This package is auto-updated.

Last update: 2023-05-10 18:42:45 UTC


This library is now part of WebP Convert and thus obsolete!

This is a solution for automatically serving WebP images instead of jpeg/pngs for browsers that supports WebP (Google Chrome, that is).

Once set up, it will automatically convert images, no matter how they are referenced. It for example also works on images referenced in CSS. As the solution does not require any change in the HTML, it can easily be integrated into any website / framework (A Wordpress adaptation was recently published on - its also on github)

NOTE: This library will be part of WebP Convert soon (depreciated, that is)


A setup consists of these parts:

  • Redirect rules that redirects JPG/PNG images to a PHP script.

  • A PHP script that serves a converted image - by calling WebPOnDemand::convert() method of this library.

  • WebPOnDemand::convert(). Detects if an existing converted image can be served. If yes, serves it (unless the original has been modified). Otherwise it converts the image using the webp-convert-and-serve library.


  • Apache or LiteSpeed web server. Can be made to work with NGINX as well. Documentation is on the roadmap.
  • PHP >= 5.6 (we are only testing down to 5.6. It should however work in 5.5 as well)
  • That one of the webp-convert converters are working (these have different requirements)


The first two steps are whether you are going to use composer or not. Not using composer? - Follow me!

1. Require this library with composer

composer require rosell-dk/webp-on-demand

2. Create the script

Create a file webp-on-demand.php, and place it in webroot, or where-ever you like in you web-application.

Here is a minimal example to get started with:

require 'vendor/autoload.php';

use WebPOnDemand\WebPOnDemand;

$source = $_GET['source'];            // Absolute file path to source file. Comes from the .htaccess
$destination = $source . '.webp';     // Store the converted images besides the original images (other options are available!)

$options = [

    'show-report' => true             // Show a conversion report instead of serving the converted image.

    // More options available!
WebPOnDemand::serve($source, $destination, $options);

3. Add redirect rules

Place the following rewrite rules in a .htaccess file in the directory you want webp-on-demand to do its magic:

<IfModule mod_rewrite.c>
    RewriteEngine On

    # Redirect images to webp-on-demand.php (if browser supports webp)
    RewriteCond %{HTTP_ACCEPT} image/webp
    RewriteRule ^(.*)\.(jpe?g|png)$ webp-on-demand.php?source=%{SCRIPT_FILENAME} [NC,L]

AddType image/webp .webp

If you have placed webp-on-demand.php in a subfolder, you will need to change the rewrite rule accordingly.

4. Validate that it works

Browse to an JPEG image. Instead of an image, you should see a conversion report. Hopefully, you get a success. Otherwise, you need to hook up to a cloud converter or try to meet the requirements for cwebp, gd or imagick. You can learn more about available options at the github page for webp-convert

Once you get a successful conversion, you can uncomment the "show-report" option in the script.

It should work now, but to be absolute sure:

  1. Visit a page on your site with an image on it, using Google Chrome.
  • Right-click the page and choose "Inspect"
  • Click the "Network" tab
  • Reload the page
  • Find a jpeg or png image in the list. In the "type" column, it should say "webp". There should also be a X-WebP-On-Demand header on the image.

5. Customizing and tweaking

Basic customizing is done by setting options in the $options array:

Other tweaking is described in docs/


The redirect rule doesn't seem to be working

If images are neither routed to the converter or a 404, it means that the redirect rule isn't taking effect. Common reasons for this includes:

  • Perhaps there are other rules in your .htaccess that interfere with the rules?
  • Perhaps your site is on Apache, but it has been configured to use Nginx to serve image files. You then need to reconfigure your server setup. Or create Nginx rules. There are some here.
  • Perhaps the server isn't configured to allow .htaccess files? Try inserting rubbish in the top of the .htaccess file and refresh. You should now see an Internal Server Error error page. If you don't, your .htaccess file is ignored. Probably you will need to set AllowOverride All in your Virtual Host. Look here for more help