shel/neos-resource-import-preprocessor

Neos Ui plugin to preprocess resource during import

1.0.0 2026-07-16 09:38 UTC

Requires

• php: >=8.2
• neos/flow: ^8.3 || ^9.0
• neos/neos-ui: ^8.3.15 || ^9.0

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9.0 || ^10.5

MIT

Published on Packagist.org on 2026-07-16 09:39 UTC

README

Processes filenames and resources during Neos CMS import to standardize naming and resize images. The processors are configurable and extendable.

Installation

composer require shel/neos-resource-import-preprocessor

Configuration

Copy the following configuration into your Settings.yaml to adjust the plugin's behavior:

Shel:
  Neos:
    ResourceImportPreprocessor:
      processFilenames:
        enabled: true
        processors:
          'replaceSpecialChars':
            class: 'Shel\Neos\ResourceImportPreprocessor\Processor\ReplaceSpecialCharsFilenameProcessor'
            options:
              # Regex pattern for characters to replace (default: replaces everything except a-zA-Z0-9._-)
              pattern: '/[^a-zA-Z0-9._-]/'
              # Replacement character (default: '-')
              replacement: '-'
      processResources:
        enabled: true
        processors:
          'resizeImages':
            class: 'Shel\Neos\ResourceImportPreprocessor\Processor\ResizeImageResourceProcessor'
            options:
              # Maximum width & height in pixels (images exceeding this will be scaled down, aspect ratio is preserved)
              maxWidth: 1920
              maxHeight: 1920
              # Options passed to Imagine's save() method (e.g. JPEG quality, PNG compression)
              saveOptions:
                quality: 85

Available processors

ReplaceSpecialCharsFilenameProcessor

Replaces special characters in filenames using a regex pattern. Useful to ensure filenames only contain safe characters.

Option	Type	Description
pattern	string	PHP regex pattern for characters to replace
replacement	string	Replacement character

ResizeImageResourceProcessor

Scales images down if they exceed the configured maximum dimensions. SVG images are skipped. Aspect ratio is always preserved.

Option	Type	Description
maxWidth	int	Maximum width in pixels
maxHeight	int	Maximum height in pixels
saveOptions	array<string,mixed>	Options passed to Imagine's save() method (see below)

The saveOptions are passed directly to Imagine's save method. Common options:

Option	Type	Supported by	Description
quality	int	JPEG, WebP, AVIF	Image quality (0–100)
png_compression_level	int	PNG	Compression level (0–9, default: 6)
jpeg_sampling_factor	string	JPEG	Chroma subsampling (e.g. '4:2:0')

Example with custom save options:

Shel:
  Neos:
    ResourceImportPreprocessor:
      processResources:
        processors:
          'resizeImages':
            class: 'Shel\Neos\ResourceImportPreprocessor\Processor\ResizeImageResourceProcessor'
            options:
              maxWidth: 1920
              maxHeight: 1920
              saveOptions:
                quality: 85
                png_compression_level: 9

Custom processors

Custom processors can be added by implementing either the Shel\Neos\ResourceImportPreprocessor\Processor\ResourceProcessorInterface or the Shel\Neos\ResourceImportPreprocessor\Processor\FilenameProcessorInterface interfaces.

Then they can be registered in the configuration.

Disabling processors

Individual processors can be disabled by setting them to null in the configuration:

Shel:
  Neos:
    ResourceImportPreprocessor:
      processFilenames:
        enabled: true
        processors:
          'replaceSpecialChars': ~

A whole processor group can be disabled by setting enabled to false:

Shel:
  Neos:
    ResourceImportPreprocessor:
      processFilenames:
        enabled: false

Sponsors

The public first release of this package was generously sponsored by Vogel communications group.

License

See License