PHPackages                             netresearch/nr-image-optimize - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. netresearch/nr-image-optimize

ActiveTypo3-cms-extension[Image & Media](/categories/media)

netresearch/nr-image-optimize
=============================

On-demand image optimization for TYPO3 with processed delivery, WebP and AVIF variants, and responsive srcset ViewHelpers.

v2.2.3(2mo ago)21.2k↓19.2%1[2 issues](https://github.com/netresearch/t3x-nr-image-optimize/issues)[1 PRs](https://github.com/netresearch/t3x-nr-image-optimize/pulls)GPL-3.0-or-laterPHPPHP >=8.2CI passing

Since Aug 21Pushed 2w ago1 watchersCompare

[ Source](https://github.com/netresearch/t3x-nr-image-optimize)[ Packagist](https://packagist.org/packages/netresearch/nr-image-optimize)[ Docs](https://extensions.typo3.org/extension/nr_image_optimize)[ RSS](/packages/netresearch-nr-image-optimize/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (18)Versions (24)Used By (0)

[![php](https://camo.githubusercontent.com/768cd40d076b95e5cf8aba0e22ea56fa7acdf64da9c535d949f499c16bd198c3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532307c253230382e332532307c253230382e342532307c253230382e352d626c75652e737667)](https://www.php.net/) [![typo3](https://camo.githubusercontent.com/8093da7d5bdb460a65d69bd0cca5a4a8482d9d5738bb582170168f1d7bc5aae6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5459504f332d31332e342532307c25323031342d6f72616e67652e737667)](https://typo3.org/) [![license](https://camo.githubusercontent.com/82dbc665347888bf88afcab2b3a48cfd53bb774d23325196509cd9919b4cecd2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6e657472657365617263682f7433782d6e722d696d6167652d6f7074696d697a65)](https://github.com/netresearch/t3x-nr-image-optimize/blob/main/LICENSE) [![ci](https://github.com/netresearch/t3x-nr-image-optimize/actions/workflows/ci.yml/badge.svg)](https://github.com/netresearch/t3x-nr-image-optimize/actions/workflows/ci.yml) [![codecov](https://camo.githubusercontent.com/d713763f4d8df3c3b05bc327c3bf9cc2b282e212897690a9444c2f1c607a44c8/68747470733a2f2f636f6465636f762e696f2f67682f6e657472657365617263682f7433782d6e722d696d6167652d6f7074696d697a652f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://app.codecov.io/gh/netresearch/t3x-nr-image-optimize) [![release](https://camo.githubusercontent.com/da1e768764cee2187e6ce13fdc30cb68158af91c20e1ec7cd1c948f971252f66/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6e657472657365617263682f7433782d6e722d696d6167652d6f7074696d697a653f736f72743d73656d766572)](https://github.com/netresearch/t3x-nr-image-optimize/releases/latest)

Image Optimization for TYPO3
----------------------------

[](#image-optimization-for-typo3)

The `nr_image_optimize` extension provides image optimization for TYPO3 on three layers:

- **On upload.** Lossless optimization runs automatically when images are added to, or replaced in, a FAL storage (via `optipng`, `gifsicle`, `jpegoptim`).
- **On demand in the frontend.** Variants are processed lazily when first requested through the `/processed/` URL, with support for modern formats (WebP, AVIF), responsive `srcset` generation, and automatic format negotiation.
- **In bulk from the CLI.** Two console commands iterate the FAL index to optimize or report optimization potential on the entire installation.

### Features

[](#features)

- **Automatic optimization on upload.** PSR-14 event listener compresses newly added or replaced images in place without re-encoding. Storages, offline drivers, and unsupported extensions are handled transparently.
- **Bulk CLI commands.** `nr:image:optimize` walks the FAL index and compresses eligible images. `nr:image:analyze`reports optimization potential without modifying files (heuristic, no binaries invoked).
- **Lazy frontend processing.** Variants are created only when a visitor first requests them through the `/processed/`URL.
- **Modern format support.** Automatic WebP and AVIF conversion with fallback to original formats.
- **Responsive images.** Built-in `SourceSetViewHelper`for `srcset` and `sizes` generation.
- **Render modes.** Choose between `cover` and `fit`resize strategies.
- **Width-based srcset.** Optional responsive `srcset`with configurable width variants and `sizes` attribute.
- **Fetch priority.** Native `fetchpriority` attribute support for Core Web Vitals optimization.
- **Middleware-based processing.** Lightweight frontend middleware intercepts `/processed/` requests.
- **Backend maintenance module.** View statistics, check system requirements, and clear processed images.

### Requirements

[](#requirements)

- PHP 8.2, 8.3, 8.4, or 8.5.
- TYPO3 13.4 or 14.
- Intervention Image library (installed via Composer automatically).

#### Optional (for on-upload and CLI optimization)

[](#optional-for-on-upload-and-cli-optimization)

Install one or more of the following binaries and make them available in `$PATH` to enable lossless compression:

- `optipng` -- for PNG files.
- `gifsicle` -- for GIF files.
- `jpegoptim` -- for JPEG files.

Paths can be overridden per binary via the `OPTIPNG_BIN`, `GIFSICLE_BIN`, and `JPEGOPTIM_BIN` environment variables. A set-but-invalid override is treated as authoritative (tool reported unavailable); there is no silent fallback to `$PATH`.

### Installation

[](#installation)

#### Via Composer (recommended)

[](#via-composer-recommended)

```
composer require netresearch/nr-image-optimize
```

#### Manual installation

[](#manual-installation)

1. Download the extension from the [TYPO3 Extension Repository](https://extensions.typo3.org/extension/nr_image_optimize).
2. Upload to `typo3conf/ext/`.
3. Activate the extension in the Extension Manager.

### Automatic optimization on upload

[](#automatic-optimization-on-upload)

After installation the PSR-14 event listener is active out of the box. Whenever an image is added or replaced on an online storage (for example via the backend file module or the REST API) the extension:

1. Normalizes the file extension (case-insensitive).
2. Checks whether an optimizer binary for that extension is installed.
3. Runs the tool in place via the `ImageOptimizer` service.
4. Restores the storage's permission-evaluation state and clears its re-entrancy guard before returning.

No configuration is required. If no optimizer binary is available the listener silently skips the file.

### CLI commands

[](#cli-commands)

#### Bulk optimize existing images

[](#bulk-optimize-existing-images)

```
# Dry-run: report what would be processed.
vendor/bin/typo3 nr:image:optimize --dry-run

# Optimize all eligible images in storage 1 with lossy JPEG
# quality 85 and EXIF stripping.
vendor/bin/typo3 nr:image:optimize \
    --storages=1 \
    --jpeg-quality=85 \
    --strip-metadata
```

Supported options:

`--dry-run`Analyze only, do not modify files.`--storages`Restrict to specific storage UIDs (comma-separated or repeated).`--jpeg-quality`Lossy JPEG quality 0--100. Omit for lossless optimization.`--strip-metadata`Remove EXIF and comments when the tool supports it.#### Analyze optimization potential

[](#analyze-optimization-potential)

```
vendor/bin/typo3 nr:image:analyze \
    --storages=1 \
    --max-width=2560 \
    --max-height=1440 \
    --min-size=512000
```

The analyzer never invokes an external tool. It estimates savings from file size and resolution and reports how much disk space could be recovered by running `nr:image:optimize`.

Supported options:

`--storages`Restrict to specific storage UIDs.`--max-width` / `--max-height`Target display box. Images larger than this box are assumed to be downscaled by `nr:image:optimize` and the estimate factors in the area reduction.`--min-size`Skip files smaller than this many bytes (default 512000). Prevents reporting on already-tiny images.### Configuration

[](#configuration)

The extension works out of the box with sensible defaults. Images accessed via the `/processed/` path are automatically optimized by the frontend middleware; uploaded images are compressed by the event listener.

#### ViewHelper usage

[](#viewhelper-usage)

```
{namespace nr=Netresearch\NrImageOptimize\ViewHelpers}

```

#### Supported parameters

[](#supported-parameters)

`path` (required)Public path to the source image (e.g. `/fileadmin/foo.jpg`). Typically generated via `f:uri.image()`.`width` / `height`Base width/height in px for the rendered ``. Defaults to `0` (auto from file / preserve aspect ratio).`set`Responsive set in the form `{maxWidth: {width: int, height: int}}` — emits per-breakpoint `` tags wrapped in a ``.`alt` / `title`HTML-escaped `alt` and `title` attributes.`class`CSS classes for the `` tag. Include `lazyload` to switch to JS-based lazy loading (`data-src`/`data-srcset`).`mode`Render mode: `cover` (default, crop/fill) or `fit`(scale inside the box).`lazyload`Add `loading="lazy"` (native lazy loading).`responsiveSrcset`Enable width-based responsive `srcset` instead of density-based 2x. Default: `false`.`widthVariants`Width variants for responsive `srcset` (comma-separated string or array). Default: `480, 576, 640, 768, 992, 1200, 1800`.`sizes`Responsive `sizes` attribute. Default: `auto, (min-width: 992px) 991px, 100vw`.`fetchpriority`Native HTML `fetchpriority` attribute (`high`, `low`, or `auto`).`attributes`Extra HTML attributes merged into the rendered tag.Note

Quality and output format are not exposed as ViewHelper arguments; they are baked into the `/processed/` URL (`q` segment, source extension). Use `f:uri.image(image: image, additionalConfiguration: ...)`to influence the generated path if needed.

### Variant URL format

[](#variant-url-format)

Processed variants are served from `/processed/..`. The mode config is a concatenation of any of `w`, `h`, `q`, `m`(width, height, quality 1--100, mode `0` = cover / `1` = fit). The processor decides at response time whether to serve the original, the `.webp` sidecar, or the `.avif` sidecar based on the `Accept` header and the `skipWebP` / `skipAvif` query flags. Path traversal sequences are rejected; `w` / `h` are clamped to 1--8192 and `q` to 1--100.

Example: `/processed/fileadmin/hero.w1200h800m0q85.jpg`.

### Extension points

[](#extension-points)

Two PSR-14 events let integrators observe the on-demand pipeline:

`ImageProcessedEvent`Dispatched after a new variant has been written to disk. Exposes source path, variant path, extension, dimensions, quality, mode, and whether WebP / AVIF sidecars were produced.`VariantServedEvent`Dispatched immediately before the response body is streamed. Reports whether the response was served from disk cache (`fromCache`).Image driver selection is handled by `ImageManagerFactory`: Imagick is preferred when the PHP extension is loaded, GD is used as a fallback. The version-agnostic `ImageReaderInterface`hides the Intervention Image v3/v4 API difference so integrators can rely on a stable contract.

### Documentation

[](#documentation)

Full documentation is available in the `Documentation/`directory and is rendered on [docs.typo3.org](https://docs.typo3.org/p/netresearch/nr-image-optimize/main/en-us/).

### Development and testing

[](#development-and-testing)

```
# Run all tests
composer ci:test

# Run specific tests
composer ci:test:php:cgl      # Code style
composer ci:test:php:lint     # PHP syntax
composer ci:test:php:phpstan  # Static analysis
composer ci:test:php:unit     # PHPUnit tests
composer ci:test:php:rector   # Code quality

# Dockerized test runner (also used by CI)
Build/Scripts/runTests.sh -s unit -p 8.4
```

### License

[](#license)

GPL-3.0-or-later. See the [LICENSE file](LICENSE) for details.

### Support

[](#support)

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/netresearch/t3x-nr-image-optimize/issues).

### Credits

[](#credits)

Developed by [Netresearch DTT GmbH](https://www.netresearch.de/).

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance72

Regular maintenance activity

Popularity23

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 67.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~17 days

Recently: every ~1 days

Total

15

Last Release

71d ago

Major Versions

0.1.5 → 1.0.02025-09-12

1.0.1 → 2.0.02025-09-17

1.1.0 → v2.2.22026-04-21

v1.1.2 → v2.2.32026-04-24

PHP version history (2 changes)1.0.0PHP ^8.1 || ^8.2 || ^8.3 || ^8.4

v2.2.2PHP >=8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/151247?v=4)[Netresearch DTT GmbH](/maintainers/netresearch)[@netresearch](https://github.com/netresearch)

---

Top Contributors

[![CybotTM](https://avatars.githubusercontent.com/u/326348?v=4)](https://github.com/CybotTM "CybotTM (215 commits)")[![magicsunday](https://avatars.githubusercontent.com/u/564393?v=4)](https://github.com/magicsunday "magicsunday (43 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (22 commits)")[![aseemann](https://avatars.githubusercontent.com/u/17200400?v=4)](https://github.com/aseemann "aseemann (19 commits)")[![Gitsko](https://avatars.githubusercontent.com/u/17161911?v=4)](https://github.com/Gitsko "Gitsko (15 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![renovate-bot](https://avatars.githubusercontent.com/u/25180681?v=4)](https://github.com/renovate-bot "renovate-bot (1 commits)")

---

Tags

extensionimageoptimizationtypo3typo3-cms-extensiontypo3-extensionimageoptimizationresponsivetypo3srcsetWebpavif

###  Code Quality

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/netresearch-nr-image-optimize/health.svg)

```
[![Health](https://phpackages.com/badges/netresearch-nr-image-optimize/health.svg)](https://phpackages.com/packages/netresearch-nr-image-optimize)
```

###  Alternatives

[pagemachine/typo3-formlog

Form log for TYPO3

23238.6k8](/packages/pagemachine-typo3-formlog)[friendsoftypo3/content-blocks

TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML

103519.9k53](/packages/friendsoftypo3-content-blocks)[netresearch/rte-ckeditor-image

Image support in CKEditor for the TYPO3 ecosystem - by Netresearch

611.1M8](/packages/netresearch-rte-ckeditor-image)[typo3/cms-install

TYPO3 CMS Install Tool - The Install Tool is used for installation, upgrade, system administration and setup tasks.

1812.3M495](/packages/typo3-cms-install)[web-vision/wv_deepltranslate

DeepL Translate (CORE) - This extension provides option to translate content element, and TCA record texts to DeepL supported languages.

33304.3k](/packages/web-vision-wv-deepltranslate)[web-vision/deepltranslate-core

DeepL Translate (CORE) - This extension provides option to translate content element, and TCA record texts to DeepL supported languages.

33142.5k8](/packages/web-vision-deepltranslate-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)