# yireo/magento2-webp2

> Magento 2 module to add WebP support to the Magento frontend

`composer require yireo/magento2-webp2`

Canonical URL: https://packagento.com/yireo/magento2-webp2

## At a glance

- **Vendor**: yireo (https://packagento.com/yireo.md)
- **Latest version**: 0.14.3 — released 2024-10-24
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/yireo/magento2-webp2 and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require yireo/magento2-webp2:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Magento 2 module to add WebP support to the Magento frontend

## README

<img src="https://img.shields.io/packagist/dt/yireo/magento2-webp2"/> <img src="https://img.shields.io/packagist/v/yireo/magento2-webp2"/> <img src="https://img.shields.io/github/languages/top/yireo/Yireo_Webp2"/> <img src="https://img.shields.io/github/last-commit/yireo/Yireo_Webp2" /> <img src="https://img.shields.io/github/sponsors/yireo"/> <img src="https://img.shields.io/badge/Hyva_Themes-Supported-3df0af.svg?longCache=true" /> <img src="https://img.shields.io/twitter/follow/yireo?style=social" />

**This module adds WebP support to Magento 2.**

### About this module
- When `<img>` tags are found on the page, the corresponding JPG or PNG is converted into WebP and a corresponding `<picture` tag is used to replace the original `<img>` tag.
- The Fotorama gallery of the Magento core product pages is replaced with WebP images without issues as well. However, the Fotorama effect loads new JPG images again, replacing the original `<picture>` tag. This shows that the Fotorama library is not scalable and may be a bad decision to use. We recommend you replace it with the [Notorama](https://github.com/robaimes/module-notorama) module instead.

> [!WARNING]
> Hyvä support is built into the latest versions of this module. Please do not use the deprecated compatibility module anymore.

### Instructions for using composer
Use composer to install this extension. Not using composer is **not** supported. Next, install the new module plus its dependency `Yireo_NextGenImages` into Magento itself: 

```bash
composer require yireo/magento2-webp2
bin/magento module:enable Yireo_Webp2 Yireo_NextGenImages
bin/magento setup:upgrade
```

Enable the module by toggling the setting in **Stores > Configuration > Yireo > Yireo WebP > Enabled**.

### System requirements
Make sure your PHP environment supports WebP: This means that the function `imagewebp` should exist in PHP. We hope to add
more checks for this in the extension itself soon. For now, just open up a PHP `phpinfo()` page and check for WebP
support. Please note that installing `libwebp` on your system is not the same as having PHP support WebP. Check the
`phpinfo()` file and add new PHP modules to PHP if needed. If in doubt, simple create a PHP script `test.php` and a line
`<?php echo (int)function_exists('imagewebp');` to it: A `1` indicates that the function is available, a `0` indicates
that it is not. Alternatively you can check for WebP using the command `php -r 'var_dump(gd_info());'`. Make sure your CLI
binary is the same as the one being called by the webserver though.

An alternative is that the `cwebp` binary from the WebP project is uploaded to your server and placed in a generic folder like `/usr/local/bin`. Make sure to grab a copy from this binary from the [rosell-dk/webp-convert](https://github.com/rosell-dk/webp-convert/tree/master/src/Convert/Converters/Binaries) project. This method is preferred because it is the fastest. But it assumes also that the binary is placed in a folder by the server administrator.

We recommend you to work on making all options work, not just one.

Please note that both tasks should be simple for developers and system administrator, but might be magical for non-technical people. If this extension is not working out of the box for you, most likely a technical person needs to take a look at your hosting environment.

### FAQ

##### Does this module support GraphQL?
Yes, but only via the additional [Yireo Webp2GraphQl](https://github.com/yireo/Yireo_Webp2GraphQl) module

##### How do I know WebP is used?
Make sure to test things with the obvious caches disabled (Full Page Cache, Block HTML Cache). Once this extension is working, catalog images (like on a category page) should be replaced with: Their `<img>` tag should be replaced with a `<picture>` tag that lists both the old image and the new WebP image. If the conversion from the old image to WebP goes well.

You can expect the HTML to be changed, so inspecting the HTML source gives a good impression. You can also use the Error Console to inspect network traffic: If some `webp` images are flying be in a default Magento environment, this usually proofs that the extension is working to some extent.

##### My CPU usage goes up. Is that normal?
Yes, it is normal. This extension does two things: It shows a WebP on the frontend of your shop. And it
generates that WebP when it is missing. Obviously, generating an image takes up system resources. And if
you have a large catalog, it is going to do more time. How much time? Do make sure to calculate this
yourself: Take an image, resize it using the `cwebp` binary and measure the time - multiply it by how many
images there are. This should give a fair estimation on how much time is needed.

Note that this extension allows for using various mechanisms (aka *convertors*). Tune the **Convertors**
settings if you want to try to optimize things. Sometimes, GD is faster than `cwebp`. Sometimes, GD just
breaks things. It depends, so you need to pick upon the responsibility to try this in your specific
environment.

Also note that this extension allows for setting an *encoding*. The default is `auto` which creates both a lossy and a lossless WebP and then picks the smallest one. Things could be twice as fast by setting this to `lossy`.

If you don't like the generation of images at all, you could also use other CLI tools instead.

##### Class 'WebPConvert\WebPConvert' not found
We only support the installation of our Magento 2 extensions, if they are installed via `composer`. Please note that - as we see it - `composer` is the only way for managing Magento depedencies. If you want to install the extension manually in `app/code`, please study the contents of `cmoposer.json` to install all dependencies of this module manually as well.

_(README truncated for .md surface. Full README on https://packagento.com/yireo/magento2-webp2.)_

## Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### [Unreleased]

### [0.14.3] - 24 October 2024
#### Fixed
- Add funding

### [0.14.2] - 23 August 2024
#### Fixed
- Guarantee return type is string #170

### [0.14.1] - 23 August 2024
#### Fixed
- Add CSP nonces to inline scripts

### [0.14.0] - 20 June 2024
#### Fixed
- Move GraphQL support in seperate [module](https://github.com/yireo/Yireo_Webp2GraphQl)

### [0.13.5] - 4 April 2024
#### Fixed
- Compatibility with Magento >=2.4.7-beta3

### [0.13.4] - 26 September 2023
#### Fixed
- Catch the correct exception when using properties of a specific exception.

### [0.13.3] - 22 September 2023
#### Fixed
- Properly check for MIME-typed (fix of #149)
- Add "webp" / "nowebp" to body class for Hyva

### [0.13.2] - 6 September 2023
#### Fixed
- Make sure convertor is called for unsupported types #149 (@kernstmediarox)

### [0.13.1] - 6 September 2023
#### Fixed
- Remove non-existing `description` in exception handling
- Move Hyva dependency to separate package `yireo/magento2-webp2-for-hyva`

### [0.13.0] - 30 August 2023
#### Added
- Copied GraphQL `url_webp` from Hyva compatibility module to here

#### Fixed
- Catch exceptions in converters by changing array to string with a foreach (@ghezelbash PR #140)

### [0.12.5] - 19 March 2023
#### Fixed
- Version bump because of new NextGenImages minor

### [0.12.4] - 13 September 2022
#### Fixed
- Implement the NextGenImages config setting `convert_images`

### [0.12.3] - 20 August 2022
#### Fixed
- Add missing semicolon #130

### [0.12.2] - 21 July 2022
#### Fixed
- Using JS native `_determineProductData` function #120 (@artbambou)
- Fix uncaught exception #127 (@jakegore)

### [0.12.1] - 2 June 2022
#### Fixed
- Skip image replacement if target URL is still empty

### [0.12.0] - 4 May 2022
#### Added
- Added ACL for user permissions (@jeroenalewijns)
- Always add `webp` CSS class to body via JS detection
- Add various integration tests
- Refactoring because of changed NextGenImages API

#### Removed
- Moved AJAX plugin for swatches to NextGenImages

### [0.11.4] - 23 August 2021
#### Fixed
- Check for double InvalidInputImageTypeException

### [0.11.3] - 23 August 2021
#### Fixed
- Fix wrong exception being caught

### [0.11.2] - 11 August 2021
#### Fixed
- Remove async from function (IE11 Support) (@barryvdh)

### [0.11.1] - 10 August 2021
#### Fixed
- Fix error to config.xml introduced in last version (@chrisastley)

### [0.11.0] - 9 August 2021
#### Added
- New option `encoding` for better performance with only `lossy` (@basvanpoppel)

### [0.10.11] - 15 July 2021
#### Fixed
- Prevent exception when GIF is renamed to JPG

### [0.10.10] - 7 July 2021
#### Fixed
- Hide all other fields if setting "Enabled" is set to 0
- Add current store to all methods

### [0.10.9] - 24 June 2021
#### Fixed
- Fix PHP Notice when gallery is missing

### [0.10.8] - 24 June 2021
#### Fixed
- Allow configuring convertors (#77)

### [0.10.7] - 6 May 2021
#### Fixed
- Prevents error if variable $imageData[$imageType] is empty (@maksymcherevko)

### [0.10.6] - 2 April 2021
#### Fixed
- Webp images not being generated if cached jpg does not exist yet #70 (@gtlt)

### [0.10.5] - 9 March 2021
#### Fixed
- Refactor conversion errors
- Move helper function to NextGenImages
- Throw exception when no conversion is needed
- Update convertor class to comply to updated interface

### [0.10.4] - 15 February 2021
#### Fixed
- Log all exceptions to NextGenImages logger

### [0.10.3] - 12 February 2021
#### Fixed
- Make sure configurable images don't throw exception

### [0.10.2] - 12 February 2021
#### Fixed
- Make sure wrong gallery images don't throw exception

### [0.10.1] - 11 February 2021
#### Fixed
- Fix JS error
- Rewrite into synchronous way of detecting WebP

_(Changelog truncated for .md surface. Full history on https://packagento.com/yireo/magento2-webp2.)_

## Recent Versions

| Version | Released |
|---|---|
| 0.14.3 | 2024-10-24 |
| 0.14.2 | 2024-08-23 |
| 0.14.1 | 2024-08-23 |
| 0.14.0 | 2024-06-20 |
| 0.13.5 | 2024-05-06 |
| 0.13.4 | 2024-04-04 |
| 0.13.3 | 2023-09-22 |
| 0.13.2 | 2023-09-06 |
| 0.13.1 | 2023-09-06 |
| 0.13.0 | 2023-08-30 |

Showing 10 of 69 versions. Full release history on https://packagento.com/yireo/magento2-webp2.

## Dependencies

### Require

| Package | Constraint |
|---|---|
| ext-gd | * |
| ext-json | * |
| ext-pcre | * |
| magento/framework | ^101.0.1\|^101.1\|^102.0\|^103.0 |
| magento/module-backend | ^100.0\|^101.0\|^102.0 |
| magento/module-config | ^101.0 |
| magento/module-store | ^101.0 |
| php | >=7.4.0 |
| psr/log | ^1 \|\| ^2 \|\| ^3 |
| rosell-dk/webp-convert | ^2.0 |
| yireo/magento2-csp-utilities | ^1.0 |
| yireo/magento2-next-gen-images | ~0.3 |

### Require (dev)

| Package | Constraint |
|---|---|
| bitexpert/phpstan-magento | ^0.3.0 |
| phpstan/phpstan | ^0.12.32 |
| phpunit/phpunit | ^9.0\|^10.0\|^11.0 |
| yireo/magento2-integration-test-helper | ^0.0.8 |

### Suggest

| Package | Constraint |
|---|---|
| yireo/magento2-webp2-for-hyva | Additional fixes with Yireo Webp2 for Hyva |
| yireo/magento2-webp2-graph-ql | GraphQL endpoints for Yireo Webp2 |

## Quality

Latest release (0.14.3) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | not tested |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Warning | 25 | 25 warnings (ruleset: Magento2) — 16 auto-fixable with phpcbf |
| PHPMD | Warning | 2 | 2 rule violations (UnusedFormalParameter:2) |
| Cpd | Pass | 0 |  |
| Composer validate | Info | 1 | valid; 1 advisory note (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 5 | 5 | – | – |
| 2.4.8 | – | 5 | 5 | – |
| 2.4.9 | – | – | 5 | 5 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["yireo/magento2-webp2"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

yireo is a Magento 2 vendor on Packagento. See https://packagento.com/yireo.md for their full catalogue.