PHPackages                             smichaelsen/melon-images - 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. smichaelsen/melon-images

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

smichaelsen/melon-images
========================

Responsive Image Management

4.0.0(1y ago)2489.3k↓25.7%9[9 issues](https://github.com/smichaelsen/melon-images/issues)[3 PRs](https://github.com/smichaelsen/melon-images/pulls)GPL-3.0PHPPHP >=7.4.0

Since Jun 16Pushed 1mo ago7 watchersCompare

[ Source](https://github.com/smichaelsen/melon-images)[ Packagist](https://packagist.org/packages/smichaelsen/melon-images)[ RSS](/packages/smichaelsen-melon-images/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (48)Used By (0)

Melon Images
============

[](#melon-images)

**Responsive Image Management for TYPO3**

This package uses the powerful responsive image cropping capabilities of TYPO3 and provides easy frontend rendering.

[![Image Cropping](doc/image-cropping.png?raw=true "Image Cropping")](doc/image-cropping.png?raw=true)

TYPO3 comes with the powerful feature of `cropVariant`s, which lets you define use cases for your image including `allowedAspectRatios` and optionally `coverAreas`. This package simplifies the configuration and frontend rendering of this feature.

Configuration:
--------------

[](#configuration)

### Files

[](#files)

You can write configuration in YAML, JSON or as PHP arrays. All examples below are in YAML, just use the same structure in JSON and in PHP.

From all loaded packages if any of the following configuration files exist, they will automatically be loaded:

- `Configuration/MelonImages.yaml`
- `Configuration/MelonImages.yml`
- `Configuration/MelonImages.json`
- `Configuration/MelonImages.config.php`

### Structure

[](#structure)

The example below configures 4 **variants** of the `tx_news_domain_model_news.fal_media` field, that are *detail*, *featured*, *teaser* and *square*. The use case is we want to use the same image in different views with different cropping. Each variant can also have different **sizes**. The *detail* variant for example is available in the sizes *big* (for tablet and desktop viewport sizes) and *phone*.

> See "Configuration Reference" bellow for a more detailed explanation

```
breakpoints:
  # phone from 0 to 479
  phone:
    to: 479

  # tablet from 480 to 1023
  tablet:
    from: 480
    to: 1023

  # desktop from 1024
  desktop:
    from: 1024

# render images in 1x and 2x
pixelDensities: [ 1, 2 ]

croppingConfiguration:
  tx_news_domain_model_news:
    # "_all" means for all news types
    _all:
      fal_media:
        variants:
          default:
            sizes:
              # The small and big size both allow free ratio and will therefore automatically be grouped in the backend with the name "Free"
              big:
                breakpoints:  [ tablet, desktop ]
                width: 943
                ratio: free
              small:
                breakpoints: [ phone ]
                width: 320
                ratio: free

          detail:
            sizes:
              big:
                breakpoints: [ tablet, phone ]
                width: 943
                height: 419

              phone:
                breakpoints: phone
                allowedRatios:
                  3by2:
                    title: 3:2
                    width: 480
                    height: 320
                  2by3:
                    title: 2:3
                    width: 320
                    height: 480

          featured:
            sizes:
              desktop:
                breakpoints: desktop
                width: 1280
                ratio: 16/9

              # The desktop and tablet size share the same ratio and will therefore automatically be grouped in the backend with the name "Featured 16/9"
              tablet:
                breakpoints: tablet
                width: 748
                ratio: 16/9

              phone:
                breakpoints: phone
                width: 480
                height: 400

          teaser:
            sizes:
              all:
                width: 480
                height: 420
                coverAreas:
                  -
                    x: 0.3
                    width: 0.7
                    y: 0.8
                    height: 0.2

          square:
            sizes:
              all:
                width: 512
                height: 512
```

### View the configuration

[](#view-the-configuration)

Beginning with TYPO3 v11 you can view your Melon Images configuration in the Configuration module.

[![Melon Images in the Configuration module](doc/configuration-module.png?raw=true)](doc/configuration-module.png?raw=true)

Rendering
---------

[](#rendering)

### Auto Render

[](#auto-render)

To render the responsive image with the correct cropping use the **ResponsivePictureViewHelper**:

```

```

The rendering (with the above config) looks something like this:

```

```

### Custom markup

[](#custom-markup)

The rendering as responsive `` tag is not always desirable. You can also get the data of the sources and fallback image and use it in your own markup:

```

```

The rendering looks something like this:

```

```

ViewHelper Reference
--------------------

[](#viewhelper-reference)

### `\Smichaelsen\MelonImages\ViewHelpers\ResponsivePictureViewHelper`

[](#smichaelsenmelonimagesviewhelpersresponsivepictureviewhelper)

Arguments:

- `fileReference`: Accepts a `\TYPO3\CMS\Core\Resource\FileReference`, a `\TYPO3\CMS\Extbase\Domain\Model\FileReference`, a `sys_file_reference`record array or a file reference uid.
- `variant`: Name of the variant to render. The names of variants are arbitrarily chosen in your configuration.
- `fallbackImageSize`: If you have an image with multiple sizes, by the last one (order is determined by order in configuration) will be used as fallback, i.e. for browsers [that do not support srcset](https://caniuse.com/#feat=picture). Here you can specify which size to use as fallback.
- `as`: The image data will be available with this variable name for custom markup rendering.
- `additionalImageAttributes`: Array of attributes that is applied to the `` tag.
- `absolute`: Set to `true` if you want image URLs to be absolute.
- `useCroppingFrom`: Here you can provide an additional FileReference that is used to crop the `fileReference`. Useful if you want to crop 2 images in exactly the same way. Accepts file references in the same form as `fileReference`.
- Universal tag attributes (`class`, `id`, `title`, ...) are available to add attributes to the `` tag.

Configuration Reference
-----------------------

[](#configuration-reference)

### 1. Breakpoints

[](#1-breakpoints)

`breakpoints`

Array of breakpoint names you can arbitrarily choose. Reference their names in the *Size Configuration* to indicate which is image size is intended for which breakpoint.

#### 1.1 Breakpoint range

[](#11-breakpoint-range)

`breakpoints.`

`from` (optional): The lower end of the breakpoint range in pixels.
`to` (optional): Indicates the upper end of the breakpoint range in pixels.

The breakpoint range is used for a media query in the responsive picture rendering in the frontend. Make sure your breakpoint ranges follow each other without gap or overlapping to ensure correct frontend rendering.

Example:

```
breakpoints:
  # phone from 0 to 470
  phone:
    to: 479

  # tablet from 480 to 1023
  tablet:
    from: 480
    to: 1023

  # desktop from 1024
  desktop:
    from: 1024
```

### 2. Pixel Densities

[](#2-pixel-densities)

`pixelDensities`

Array or comma separated list of pixel densities that are rendered in the responsive picture elements. If you don't know what values you should put here `1,2` is good choice. It renders images in standard size (`1`) and double size for displays that support double pixel density (`2`).

Example:

```
pixelDensities:
  - 1
  - 2
```

### 3. Progressive Image File Formats

[](#3-progressive-image-file-formats)

`imageFileFormats`

By default TYPO3 will automatically choose broadly supported file formats like `jpg` or `png`, depending on the source image. You can override this behavior by specifying a list of file formats that should be used for progressive image rendering.

Example:

```
imageFileFormats:
  - webp
  - _default
```

This will add `` elements to the responsive picture element with the `webp` file formats. As well as the default file format. You can also omit the default file format:

```
imageFileFormats:
  - webp
```

The fallback image will always be rendered in the `_default` file format to support legacy browsers.

Make sure you add the desired file extensions to `$GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']`.

### 4. Per Table and Type Configuration

[](#4-per-table-and-type-configuration)

`croppingConfiguration..`

If the configuration should apply to all records of the `` regardless of the ``, use `_all` as record type.

Example:

```
croppingConfiguration:
  tx_news_domain_model_news:
    _all:
      # "_all" means for all news types
  tt_content:
    textmedia:
      # applies only to tt_content records with type (CType) textmedia
```

### 5. Per Field Configuration

[](#5-per-field-configuration)

`croppingConfiguration...`

The field must be:

1. Either a FAL field (i.e. an `inline` type field holding `sys_file_reference` records)

**or**

2. A field of the type `inline`, `select` or `group` referencing other records (See *7. Inline Records*)

### 6. Variants

[](#6-variants)

`croppingConfiguration....variants`

Array of variant names you can arbitrarily choose. Think of a variant as of situations you want to use an image in. If want to use it in a list view, a detail view and a social media sharing format, your structure could look like in this example:

```
croppingConfiguration:
  tx_news_domain_model_news:
    _all:
      variants:
        list:
          # ...
        detail:
          # ...
        openGraph:
          # ...
```

Reuse the variant name in the `variant` attribute of the `melon:responsivePicture` ViewHelper.

### 6.1 Variant Configuration

[](#61-variant-configuration)

`croppingConfiguration....variants.`

`title` (optional): Title of the variant that is shown to the backend user. Per default the variant name (with the first letter uppercased) is used.

### 7. Sizes

[](#7-sizes)

`croppingConfiguration....variants..sizes`

Array of size names you can arbitrarily choose. Here you define how many different sizes you need of your image in the given variant. Imagine you need to render the detail image of an article in 3 different sizes, but the list image only in one size because a responsive grid in the frontend takes care of the images always being displayed in the same size on all devices, your structure could look like in this example:

```
croppingConfiguration:
  tx_news_domain_model_news:
    _all:
      variants:
        list:
          sizes:
            unisize:
              # ...
        detail:
          sizes:
            small:
              # ...
            medium:
              # ...
            big:
              # ...
```

### 7.1 Size Configuration

[](#71-size-configuration)

`croppingConfiguration....variants..sizes.`

`breakpoints` (optional): Comma separated list of breakpoint names (See *1. Breakpoints*) that this size is used for. If omitted the size will have no media query condition is used on all screens - recommended if you use only one size for the given variant.
`width` (optional): Width in pixels the image is rendered in.
`height` (optional): Height in pixels the image is rendered in.
`ratio` (optional): If the ratio is given (in the x/y, e.g. 16/9) the width or the height may be omitted. The height can be calculated by width and ratio. The width can be calculated by height and ratio. It is also possible to specify a ratio as `free`, which configures the cropping editor to allow croppings with arbitrary image dimensions. *If multiple sizes share the same ratios they are grouped in the backend so that the editor sets a single cropping for them.*In the frontend they are still rendered as different sizes for different breakpoints.

If you provide `width` and `height` it results in a fixed aspect ratio that is enforced in the backend cropping tool. Neat!

### 7.1.1 Cover Areas

[](#711-cover-areas)

`croppingConfiguration....variants..sizes..coverAreas`

Array of cover areas. See the [TCA Reference](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ColumnsConfig/Type/ImageManipulation/Properties/CropVariants.html#define-cover-areas) for details on that feature.

Each cover area needs has following properties:

`x:` Horizontal position of the upper left corner of the cover area from 0 to 1 (0 is the left, 1 the right edge of the image)
`y:` Vertical Position of the upper left corner of the cover area from 0 to 1 (0 is the top, 1 the bottom edge of the image)
`width` Width of the cover area from 0 to 1 (1 being 100% of the image width)
`height` Height of the cover area from 0 to 1 (1 being 100% of the image height)

Example:

```
croppingConfiguration:
  tx_news_domain_model_news:
    _all:
      variants:
        detail:
          sizes:
            big:
              coverAreas:
                -
                  # Indicate to the editor that the right half of the image might be covered in the frontend
                  x: 0.5
                  y: 0
                  width: 0.5
                  height: 1
```

### 7.1.2 Focus Area

[](#712-focus-area)

`croppingConfiguration....variants..sizes..focusArea`

See the [TCA Reference](https://docs.typo3.org/typo3cms/TCAReference/ColumnsConfig/Type/ImageManipulation.html#cropvariants) for details on that feature.

`x:` Horizontal position of the upper left corner of the initial focus area from 0 to 1 (0 is the left, 1 the right edge of the image)
`y:` Vertical Position of the upper left corner of the initial focus area from 0 to 1 (0 is the top, 1 the bottom edge of the image)
`width` Width of the initial focus area from 0 to 1 (1 being 100% of the image width)
`height` Height of the initial focus area from 0 to 1 (1 being 100% of the image height)

The position and dimensions of the focus area can be adjusted by the editor in the backend to mark the crucial area of the image.

Setting a focus area will have no effect on the backend image processing or its rendering with the `melon:responsivePicture` ViewHelper. If you want to use this feature you need to take care of the frontend implementation.

Example:

```
croppingConfiguration:
  tx_news_domain_model_news:
    _all:
      variants:
        detail:
          sizes:
            big:
              focusArea:
                x: 0.4
                y: 0.4
                width: 0.2
                height: 0.2
```

### 8. Inline Records (Nested Records)

[](#8-inline-records-nested-records)

`croppingConfiguration.....`

If your field references other records that have image fields in them you can use this structure to configure.

Example: You have a "Contacts" content element, which a field field, that holds an arbitrary number of contact records. Each contact has a square photo.

```
croppingConfiguration:
  # We want to target content elements of the type tx_myext_contacts
  tt_content:
    tx_myext_contacts:
      # Field "contacts" holds the relation to the contact records
      contacts:
        # The configuration is valid for any type of contact record
        _all:
          # Field "image" holds the photo of a contact
          image:
            # variant "list" with one size "unisize"
            variants:
              list:
                sizes:
                  unisize:
                    width: 200
                    height: 200
```

You can nest this configuration as deep as you need it to be.

Power user hints
----------------

[](#power-user-hints)

If you use YAML anchors to reuse certain configuration snippets, prefix them with `__`. This way they will only be available during YAML parsing and will automatically be stripped afterwards in the parsed configuration.

```
# This follows facebook's recommendation for og:image of 1200x630
__openGraph: &open-graph
  title: Social Sharing
  sizes:
    all:
      width: 1200
      ratio: 1.91/1

```

Breaking Changes
----------------

[](#breaking-changes)

### From 2.x to 3.x

[](#from-2x-to-3x)

Configuration in TypoScript is not possible anymore. Just convert it to YAML, the same scheme is still supported.

### From 1.x to 2.x

[](#from-1x-to-2x)

If you're using custom markup to output your image the width and height are now enclosed in a `\Smichaelsen\MelonImages\Domain\Dto\Dimensions` object. In practice this means you will have to change `fallbackImageData.width` to `fallbackImageData.dimensions.width`.

### From 0.8 to 0.9

[](#from-08-to-09)

With upgrading you will lose all cropping information. You need to crop the images again the backend.

###  Health Score

53

—

FairBetter than 97% of packages

Maintenance58

Moderate activity, may be stable

Popularity42

Moderate usage in the ecosystem

Community20

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor1

Top contributor holds 81% 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 ~89 days

Recently: every ~209 days

Total

30

Last Release

677d ago

Major Versions

0.11.1 → 1.0.02019-05-24

1.1.0 → 2.02020-09-29

2.0 → 3.0.02021-08-16

3.4.0 → 4.0.02024-07-10

PHP version history (3 changes)0.7.1PHP 7.1.\*

1.0.0PHP >=7.1.0

3.0.0PHP >=7.4.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/886face3e57e668db2bf95d62325f423baf7e9d8949a9e4c84d3a0e6c3891920?d=identicon)[smichaelsen](/maintainers/smichaelsen)

---

Top Contributors

[![smichaelsen](https://avatars.githubusercontent.com/u/912435?v=4)](https://github.com/smichaelsen "smichaelsen (111 commits)")[![georgringer](https://avatars.githubusercontent.com/u/1905663?v=4)](https://github.com/georgringer "georgringer (12 commits)")[![helhum](https://avatars.githubusercontent.com/u/904370?v=4)](https://github.com/helhum "helhum (5 commits)")[![amirarends](https://avatars.githubusercontent.com/u/48568142?v=4)](https://github.com/amirarends "amirarends (4 commits)")[![christian-fries](https://avatars.githubusercontent.com/u/852644?v=4)](https://github.com/christian-fries "christian-fries (2 commits)")[![milicj](https://avatars.githubusercontent.com/u/87117603?v=4)](https://github.com/milicj "milicj (1 commits)")[![chesio](https://avatars.githubusercontent.com/u/2021167?v=4)](https://github.com/chesio "chesio (1 commits)")[![zeaiso](https://avatars.githubusercontent.com/u/77481196?v=4)](https://github.com/zeaiso "zeaiso (1 commits)")

---

Tags

typo3-cms-extension

###  Code Quality

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/smichaelsen-melon-images/health.svg)

```
[![Health](https://phpackages.com/badges/smichaelsen-melon-images/health.svg)](https://phpackages.com/packages/smichaelsen-melon-images)
```

###  Alternatives

[netresearch/rte-ckeditor-image

Image support in CKEditor for the TYPO3 ecosystem - by Netresearch

63991.3k4](/packages/netresearch-rte-ckeditor-image)[christophlehmann/imageoptimizer

Optimize uploaded/processed images with binaries of your choice

46501.8k](/packages/christophlehmann-imageoptimizer)[plan2net/webp

Creates WebP copies for images (TYPO3 CMS)

661.4M3](/packages/plan2net-webp)[sitegeist/sms-responsive-images

Provides ViewHelpers and configuration to render valid responsive images based on TYPO3's image cropping tool.

34493.1k2](/packages/sitegeist-sms-responsive-images)[lochmueller/focuspoint

Focuspoint integrate the focal point method to crop images in the frontend of the web page. Use the jQuery-focuspoint plugin (https://github.com/jonom/jquery-focuspoint example http://jonom.github.io/jquery-focuspoint/demos/helper/index.html) to crop the images. Use the function as wizard in the file list view and directly in the content element.

23179.1k](/packages/lochmueller-focuspoint)[schmitzal/tinyimg

Image compression for all pngs and jpgs uploaded to the backend (using the tinypng API)

16125.5k](/packages/schmitzal-tinyimg)

PHPackages © 2026

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