PHPackages                             sitegeist/kaleidoscope-valueobjects - 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. [Utility & Helpers](/categories/utility)
4. /
5. sitegeist/kaleidoscope-valueobjects

ActiveNeos-package[Utility & Helpers](/categories/utility)

sitegeist/kaleidoscope-valueobjects
===================================

Value objects and editors based on Kaleidoscope

v1.6.0(3mo ago)24.9k↓12.6%[1 issues](https://github.com/sitegeist/Sitegeist.Kaleidoscope.ValueObjects/issues)2GPL-3.0-or-laterJavaScriptPHP >=8.2CI passing

Since Mar 7Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/sitegeist/Sitegeist.Kaleidoscope.ValueObjects)[ Packagist](https://packagist.org/packages/sitegeist/kaleidoscope-valueobjects)[ RSS](/packages/sitegeist-kaleidoscope-valueobjects/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (34)Used By (2)

Sitegeist.Kaleidoscope.ValueObjects
===================================

[](#sitegeistkaleidoscopevalueobjects)

Proxy objects for ImageSources
------------------------------

[](#proxy-objects-for-imagesources)

Proxy objects for ImageSources that can be edited in the inspector directly and allow editing of images and image collections together with alt and title for each item.

### Authors & Sponsors

[](#authors--sponsors)

- Christian Pansch -
- Martin Ficzel -

*The development and the public-releases of this package is generously sponsored by our employer .*

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

[](#installation)

Sitegeist.Kaleidoscope.ValueObjects is available via packagist run `composer require sitegeist/kaleidoscope-valueobjects`. We use semantic versioning so every breaking change will increase the major-version number.

Usage
-----

[](#usage)

### NodeTypes

[](#nodetypes)

Single images are edited via property type `Sitegeist\Kaleidoscope\ValueObjects\ImageSourceProxy`.

```
    imageSourceProxy:
      type: 'Sitegeist\Kaleidoscope\ValueObjects\ImageSourceProxy'
      defaultValue: null
      ui:
        label: 'Image'
        inspector:
          group: imageWithMetadata
```

Lists of images are edited via property type `Sitegeist\Kaleidoscope\ValueObjects\ImageSourceProxyCollection`.

```
    imageSourceProxyCollection:
      type: 'Sitegeist\Kaleidoscope\ValueObjects\ImageSourceProxyCollection'
      defaultValue: []
      ui:
        label: 'Images'
        inspector:
          group: imageWithMetadata
```

### Inspector Editor Configuration

[](#inspector-editor-configuration)

For properties of type `Sitegeist\Kaleidoscope\ValueObjects\ImageSourceProxy` and `...\ImageSourceProxyCollection`dedicated inspector editors `Sitegeist.Kaleidoscope.ValueObjects/Inspector/Editors/AssetWithMetadataEditor` and `.../AssetWithMetadataCollectionEditor`are provided and configured for the Proxy Objects. The Editor Configuration is derived from the options as the Neos `ImageEditor`as is documented [here](https://neos.readthedocs.io/en/stable/References/PropertyEditorReference.html#property-type-image-neos-media-domain-model-imageinterface-imageeditor-image-selection-upload-editor).

#### Options Reference:

[](#options-reference)

- `maximumFileSize` (string) Set the maximum allowed file size to be uploaded. Accepts numeric or formatted string values, e.g. "204800" or "204800b" or "2kb". Defaults to the maximum allowed upload size configured in php.ini
- `constraints`
    - `mediaTypes` (array) If set, the media browser and file upload will be limited to assets with the specified media type. Default `['image/*']`Example: `['image/png', 'image/jpeg']`Note: Due to technical limitations the media browser currently ignores the media sub type, so `image/png` has the same effect as `image/*`
    - `assetSources` (array) If set, the media browser will be limited to assets of the specified asset source. Default: `[]` (all asset sources) Example: `['neos', 'custom_asset_source]`
- `features`
    - `crop` (boolean) If `true`, enable image cropping. Default `true`.
    - `upload` (boolean) If `true`, enable Upload button, allowing new files to be uploaded directly in the editor. Default `true`.
    - `mediaBrowser` (boolean) If `true`, enable Media Browser button. Default `true`.
- `resize` (boolean) If `true`, enable image resizing. Default `FALSE`.
- `crop` crop-related options. Only relevant if `features.crop` is enabled.
    - `aspectRatio`
        - `forceCrop` (boolean) Show the crop dialog on image upload
            - `locked` Locks the aspect ratio to a specific width/height ratio
                - `width` (integer) width of the aspect ratio which shall be enforced
                - `height` (integer) height of the aspect ratio which shall be enforced
            - `options` aspect-ratio presets. Only effective if `locked` is not set.
                - `[presetIdentifier]`
                    - `width` (required integer) the width of the aspect ratio preset
                    - `height` (required integer) the height of the aspect ratio preset
                    - `label` (string) human-readable name of the aspect ratio preset
            - `enableOriginal` (boolean) If `true`, the image ratio of the original image can be chosen in the selector. Only effective if `locked` is not set. Default `true`.
            - `allowCustom` (boolean) If `true`, a completely custom image ratio can be chosen. Only effective if `locked`is not set. Default `true`.
            - `defaultOption` (string) default aspect ratio option to be chosen if no cropping has been applied already.
- `disabled` (boolean) If `true`, disables the ImageEditor.

### EEL & Fusion

[](#eel--fusion)

When one of the proxy objects is passed to a `Sitegeist.Kaleidoscope.Image|Picture|Source` prototype as `imageSource`the value is automatically converted into an `ImageSourceInterface`.

```
    example = Sitegeist.Kaleidoscope:Image {
        imageSource = ${q(node).property('imageSourceProxy')}
    }

```

If you need more control over the conversion from proxies to image sources you can use you can use the `Kaleidoscope.ValueObjects` helper. Be careful as those methods only allow the `ImageSourceProxy`, `ImageSourceProxyCollection` and `null` as parameter.

```
imageSource = ${Sitegeist.Kaleidoscope.ValueObjects.unwrapProxy(q(node).property('imageSourceProxy'))}
imageSources = ${Sitegeist.Kaleidoscope.ValueObjects.unwrapProxyCollection(q(node).property('imageSourceProxyCollection'))}

```

There are also fusion prototypes that will check the type of the given value convert `ImageSourceProxy`, `ImageSourceProxyCollection` but leave all other values untouched.

```
# read imageSourceProxy and convert to imageSource
imageSource = ${q(node).property('imageSourceProxy')}
imageSource.@process.unwrapImageSourceProxy = Sitegeist.Kaleidoscope.ValueObjects:ImageSourceProxyUnwrapper

imageSources = ${q(node).property('imageSourceProxyCollection')}
imageSources.@process.unwrapImageSourceProxy = Sitegeist.Kaleidoscope.ValueObjects:ImageSourceProxyCollectionUnwrapper

```

Migration of existing data
--------------------------

[](#migration-of-existing-data)

For Neos 8 the package `Sitegeist.Kaleidoscope.ValueObjects.Migrations` provides migrations to convert existing Nodes to the new ImageSourceProxy and ImageSourceProxyCollection. The package can be installed via `composer require sitegeist/kaleidoscope-valueobjects-migrations`.

Migrations for Neos 9 are not yet available but will be in a separate package.

Development
-----------

[](#development)

To build the javascript for the inspector-editors the following docker commands can be used.

```
# run development build
docker run -it -v $(pwd):/app -w /app node:23 sh -c "yarn && yarn build:dev"

# run production build
docker run -it -v $(pwd):/app -w /app node:23 sh -c "yarn && yarn build"
```

Contribution
------------

[](#contribution)

We will gladly accept contributions. Please send us pull requests.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance69

Regular maintenance activity

Popularity26

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 59.3% 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 ~21 days

Recently: every ~12 days

Total

16

Last Release

110d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/51e0a02d8e12b73949ec858638aa7e295e103022cc5a879f86ac8532c2c170bd?d=identicon)[sitegeist](/maintainers/sitegeist)

![](https://www.gravatar.com/avatar/829b4ccb51e8cff3c1e4b59d60cfe8d1b86f6d77fc31a6b3fc99227f432542ca?d=identicon)[mficzel](/maintainers/mficzel)

---

Top Contributors

[![mficzel](https://avatars.githubusercontent.com/u/1309380?v=4)](https://github.com/mficzel "mficzel (67 commits)")[![Christian-Pansch](https://avatars.githubusercontent.com/u/227752200?v=4)](https://github.com/Christian-Pansch "Christian-Pansch (26 commits)")[![Alvadda](https://avatars.githubusercontent.com/u/58438582?v=4)](https://github.com/Alvadda "Alvadda (20 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/sitegeist-kaleidoscope-valueobjects/health.svg)

```
[![Health](https://phpackages.com/badges/sitegeist-kaleidoscope-valueobjects/health.svg)](https://phpackages.com/packages/sitegeist-kaleidoscope-valueobjects)
```

###  Alternatives

[sitegeist/monocle

An living-styleguide for Neos that is based on the actual fusion-code

45315.9k10](/packages/sitegeist-monocle)[sitegeist/kaleidoscope

Responsive-images for Neos

29352.4k10](/packages/sitegeist-kaleidoscope)[kaufmanndigital/gdpr-cookieconsent

A ready-to-run package, that integrates an advanced cookie consent banner into your Neos CMS site.

2540.7k](/packages/kaufmanndigital-gdpr-cookieconsent)[neos/seo

SEO configuration and tools for Neos

13990.5k24](/packages/neos-seo)[shel/neos-colorpicker

A plugin for Neos CMS which provides a colorpicker editor

1494.4k6](/packages/shel-neos-colorpicker)[shel/neos-hyphens

A plugin for Neos CMS which provides hyphens for the inline editor

20200.7k1](/packages/shel-neos-hyphens)

PHPackages © 2026

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