PHPackages                             componenta/image-converter - 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. componenta/image-converter

ActiveLibrary[Image & Media](/categories/media)

componenta/image-converter
==========================

Image conversion helpers for Componenta

v1.0.0(1mo ago)01MITPHPPHP ^8.4

Since Jun 16Pushed 1mo agoCompare

[ Source](https://github.com/componenta/image-converter)[ Packagist](https://packagist.org/packages/componenta/image-converter)[ RSS](/packages/componenta-image-converter/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

Componenta Image Converter
==========================

[](#componenta-image-converter)

Image conversion contracts and GD-backed image converters for Componenta. The package keeps low-level GD calls behind small contracts and provides an `ImageConverter` orchestrator that selects a target converter by requested output type and validates the source MIME type through `componenta/mimetype-detector`.

Requirements
------------

[](#requirements)

- PHP 8.4+
- GD extension
- `componenta/mimetype-detector` for source MIME detection

Installation
------------

[](#installation)

```
composer require componenta/image-converter
```

The package declares `Componenta\Image\ConfigProvider` in `extra.componenta.config-providers`. When `componenta/composer-plugin` is installed, the provider is added to the generated provider list automatically.

Main API
--------

[](#main-api)

`ImageConverterInterface` is the low-level contract implemented by single-target converters:

```
use Componenta\Image\ImageConverterInterface;
use Psr\Http\Message\StreamInterface;

interface ImageConverterInterface
{
    public function convert(string|StreamInterface $source, ?int $quality = null): ConvertedImage;

    public function supports(string $mimeType): bool;
}
```

`ImageConverter` is the orchestrator for application code that needs to choose the target format at runtime:

```
use Componenta\Image\ImageConverter;

if ($converter->canConvert($source, 'webp')) {
    $image = $converter->convert($source, 'webp', quality: 82);
}

$image->content;   // binary converted bytes
$image->mimeType;  // image/webp
$image->extension; // webp
$image->size;      // byte length
```

`$source` may be a binary string or `Psr\Http\Message\StreamInterface`. Target types accept short names and MIME types, for example `webp`, `image/webp`, `jpg`, `jpeg`, `image/jpeg`, `png`, and `image/avif`.

Built-In Converters
-------------------

[](#built-in-converters)

ConverterTargetSupported source MIME types`GdWebPConverter``webp`, `image/webp`JPEG, PNG, BMP. GIF is intentionally not supported because GD would drop animation.`GdJpegConverter``jpeg`, `jpg`, `image/jpeg`PNG, WebP, AVIF, BMP. Alpha is flattened onto a white background.`GdPngConverter``png`, `image/png`JPEG, WebP, AVIF, BMP. Alpha is preserved when available.`GdAvifConverter``avif`, `image/avif`JPEG, PNG, WebP, BMP when the local GD build supports `imageavif()`.For JPEG, WebP, and AVIF, quality is `0..100`. For PNG, the same quality range is mapped to GD compression level `0..9`.

Extension Points
----------------

[](#extension-points)

Implement `ImageConverterInterface` for a new backend or target format. If the converter also implements `ImageConversionTargetsProviderInterface`, the orchestrator can read its `conversionTargets` property automatically:

```
use Componenta\Image\ImageConversionTargetsProviderInterface;
use Componenta\Image\ImageConverterInterface;

final class ImagickWebPConverter implements ImageConverterInterface, ImageConversionTargetsProviderInterface
{
    public array $conversionTargets {
        get => ['webp', 'image/webp'];
    }

    // convert() and supports()
}
```

Converters can be added after construction:

```
$converter->addConverter(new ImagickWebPConverter());
$converter->addConverter(new CustomFormatConverter(), 'custom', 'image/x-custom');
```

When target types are passed explicitly to `addConverter()`, they override the optional provider property for registration.

Failure Model
-------------

[](#failure-model)

`ImageConverter` throws `ConversionException` when:

- no converter is registered for the requested target type;
- the source MIME type cannot be detected;
- the target converter does not support the detected source MIME type;
- GD cannot decode or encode the image;
- quality is outside `0..100`.

Treat conversion as an infrastructure boundary: validate upload constraints before conversion and handle conversion failure as a user-facing invalid media error.

DI Registration
---------------

[](#di-registration)

`ConfigProvider` registers:

- `ImageConverter` through `ImageConverterFactory`;
- `GdWebPConverter`, `GdJpegConverter`, `GdPngConverter`, and `GdAvifConverter`;
- `ImageConverterInterface` as an alias to `GdWebPConverter` for code that wants a fixed WebP converter.

`ImageConverterFactory` uses `MimeTypeDetectorInterface` from the container when available and falls back to `FinfoDetector`.

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance91

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

43d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20490712?v=4)[Andrey Shelamkoff](/maintainers/Shelamkoff)[@Shelamkoff](https://github.com/Shelamkoff)

---

Top Contributors

[![Shelamkoff](https://avatars.githubusercontent.com/u/20490712?v=4)](https://github.com/Shelamkoff "Shelamkoff (1 commits)")

### Embed Badge

![Health badge](/badges/componenta-image-converter/health.svg)

```
[![Health](https://phpackages.com/badges/componenta-image-converter/health.svg)](https://phpackages.com/packages/componenta-image-converter)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.4k87.2M2.2k](/packages/symfony-symfony)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k17](/packages/tempest-framework)[cakephp/cakephp

The CakePHP framework

8.8k19.5M1.8k](/packages/cakephp-cakephp)[moonshine/moonshine

Laravel administration panel

1.3k253.1k86](/packages/moonshine-moonshine)[bref/bref

Bref is a framework to write and deploy serverless PHP applications on AWS Lambda.

3.4k10.6M68](/packages/bref-bref)[contao/core-bundle

Contao Open Source CMS

1231.6M2.9k](/packages/contao-core-bundle)

PHPackages © 2026

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