move-elevator/typo3-image-compression

Automatically compress images using TinyPNG API, local tools (jpegoptim, optipng, etc.), or ImageMagick/GraphicsMagick

1.0.0 2025-12-05 11:49 UTC

Requires

• php: ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
• ext-fileinfo: *
• doctrine/dbal: ^3.8 || ^4.0
• psr/container: ^1.1 || ^2.0
• psr/log: ^2.0 || ^3.0
• symfony/console: ^6.4 || ^7.0
• tinify/tinify: ^1.6
• typo3/cms-backend: ^12.4 || ^13.4 || ^14.0
• typo3/cms-core: ^12.4 || ^13.4 || ^14.0
• typo3/cms-extbase: ^12.4 || ^13.4 || ^14.0
• typo3/cms-filelist: ^12.4 || ^13.4 || ^14.0
• typo3/cms-fluid: ^12.4 || ^13.4 || ^14.0
• typo3/cms-reports: ^12.4 || ^13.4 || ^14.0

Requires (Dev)

• eliashaeussler/version-bumper: ^2.4 || ^3.0
• phpunit/phpcov: ^10.0 || ^11.0
• phpunit/phpunit: ^11.0 || ^12.0
• typo3/cms-lowlevel: ^12.4 || ^13.4 || ^14.0

GPL-2.0-or-later

• Konrad Michalik
• Ronny Hauptvogel

• image
• compression
• ImageMagick
• optimization
• typo3
• jpegoptim
• tinypng
• typo3-extension

README

TYPO3 extension typo3_image_compression

This TYPO3 extension automatically compresses images uploaded to the TYPO3 backend. Choose between the TinyPNG API for best results or local tools for cost-free compression.

Features

• Multiple compression providers: TinyPNG API, local optimized tools, or ImageMagick/GraphicsMagick
• Automatic compression of JPG, PNG, GIF, AVIF and WebP images on upload
• CLI command for batch processing existing images
• Configurable quality settings for local compression
• Image compression statistic in the system information toolbar
• Image compression info in sys_file_metadata edit view

Provider Comparison

Provider	Tools	Compression	Cost	Best For
tinify	TinyPNG API	~70-80%	API quota	Production, best quality
local-tools	jpegoptim, optipng, pngquant, gifsicle, cwebp	~50-60%	Free	Self-hosted, no API costs
local-basic	ImageMagick / GraphicsMagick	~30-40%	Free	JPEG only, quick setup

🔥 Installation

Requirements

• TYPO3 >= 12.4
• PHP 8.2+

Composer

composer require move-elevator/typo3-image-compression

TER

Download the zip file from TYPO3 extension repository (TER).

🧰 Configuration

Configure the extension in Admin Tools > Settings > Extension Configuration.

Provider

Choose the compression provider from the dropdown.

tinify (TinyPNG API)

1. Register at TinyPNG Developers to obtain your API key
2. Set Provider to tinify and enter your API key
3. Free tier: 500 compressions/month, paid upgrades via TinyPNG dashboard

Warning

Be aware that the free API limit (500 compressions/month) can be exhausted quickly on large sites with many existing images.

local-tools (Optimized Tools)

Install the required tools on your server:

# Debian/Ubuntu
apt install jpegoptim optipng pngquant gifsicle webp

# macOS (Homebrew)
brew install jpegoptim optipng pngquant gifsicle webp

Set Provider to local-tools. The extension auto-detects available tools.

local-basic (ImageMagick/GraphicsMagick)

No additional installation needed - uses TYPO3's configured graphics processor. Set Provider to local-basic.

Quality Settings

For local providers, configure quality (1-100) for JPEG, PNG, and WebP compression.

📊 Usage

Automatic Compression

Once configured, all images (with supported mime type) uploaded via the TYPO3 backend will be automatically compressed.

Batch Processing (CLI)

For existing projects, a CLI command is available to compress images that were uploaded before the extension was installed.

# Compress up to 100 original images (default)
vendor/bin/typo3 imagecompression:compressImages

# Compress up to 50 images
vendor/bin/typo3 imagecompression:compressImages 50

# Also compress processed files (thumbnails, crops, etc.)
vendor/bin/typo3 imagecompression:compressImages --include-processed

# Retry failed compressions
vendor/bin/typo3 imagecompression:compressImages --retry-errors

# Combine options
vendor/bin/typo3 imagecompression:compressImages 200 --include-processed --retry-errors

Argument/Option	Description
limit	Number of images to process (default: 100)
--include-processed, -p	Also compress processed files (thumbnails, crops). By default, only original files are compressed to save API quota.
--retry-errors, -r	Retry compression for files that previously failed. On success, the error status is cleared.

Tip

When using Tinify (TinyPNG API), we recommend not using --include-processed to conserve your API quota. Processed files are regenerated from the already-compressed originals.

Important

Before running the CLI command, ensure your TYPO3 file index is up to date. Use the scheduler task "File Abstraction Layer: Update storage index" to update the index.

System Information Toolbar

The extension displays the current API usage (TinyPNG) or compression statistics in the TYPO3 backend toolbar.

Status Report

A detailed compression report is available in Admin Tools > System Reports. It shows the active provider, compression statistics for original and processed files, and API usage for TinyPNG.

File Metadata

The compression status of individual files is displayed in the file metadata form (sys_file_metadata). Edit a file's metadata to see whether it has been compressed, and any error messages if compression failed.

💛 Acknowledgements

This project is a fork and further development of the great tinyimg extension.

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 2.0 (or later).