PHPackages                             heimrichhannot/contao-filename-sanitizer-bundle - 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. [Validation & Sanitization](/categories/validation)
4. /
5. heimrichhannot/contao-filename-sanitizer-bundle

ActiveContao-bundle[Validation & Sanitization](/categories/validation)

heimrichhannot/contao-filename-sanitizer-bundle
===============================================

This bundle offers functionality for sanitizing filenames, i.e. replacing unwanted characters like whitespaces, non-ascii characters, ... (e.g. while uploading them to the CMS).

2.4.3(1y ago)38.0k[3 issues](https://github.com/heimrichhannot/contao-filename-sanitizer-bundle/issues)LGPL-3.0-or-laterPHPPHP ^7.4||^8.0CI failing

Since Jan 11Pushed 1y ago6 watchersCompare

[ Source](https://github.com/heimrichhannot/contao-filename-sanitizer-bundle)[ Packagist](https://packagist.org/packages/heimrichhannot/contao-filename-sanitizer-bundle)[ RSS](/packages/heimrichhannot-contao-filename-sanitizer-bundle/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (5)Dependencies (17)Versions (21)Used By (0)

Contao Filename Sanitizer Bundle
================================

[](#contao-filename-sanitizer-bundle)

This bundle offers functionality for sanitizing filenames, i.e. replacing unwanted characters like whitespaces, non-ascii characters, ... (e.g. while uploading them to the CMS).

Features
--------

[](#features)

- sanitize filenames while uploading files using the Contao file manager
- sanitize filenames while saving a given file using the Contao file manager
- configurable sanitizing rules:
    - valid alphabets (the characters which are valid in the end -> "whitelist")
    - trimming
    - replacing of repeating (consecutive) hyphens or underscores
- service is also available for various other use cases besides file upload
- define a set of 1:1 character replacements (useful for German umlauts, i.e. ä => ae)
- use the `SanitizeCommand` in order to sanitize the filenames of files/folders already in the system and automatically create htaccess rewrite rules in order to keep deep links working

Default sanitizing rules after installation of this bundle
----------------------------------------------------------

[](#default-sanitizing-rules-after-installation-of-this-bundle)

[![configuration](doc/images/config.png)](doc/images/config.png)

Configuration in Contao's global settings

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

[](#installation)

Install via composer: `composer require heimrichhannot/contao-filename-sanitizer-bundle` and update your database.

Configuration
-------------

[](#configuration)

You can configure the sanitizing rules in the global Contao settings under "file names".

Important notes
---------------

[](#important-notes)

### When is the sanitizing done exactly?

[](#when-is-the-sanitizing-done-exactly)

There are different situations where the filename sanitizing (which affects files and folders) takes place:

1. A new file is uploaded by using Contao's file manager (files uploaded by FTP are of course not covered)
2. An already existing file is saved by using Contao's file manager.
3. An already existing folder is saved by using Contao's file manager. **Files inside the folder are NOT sanitized automatically!**
4. By using the command `huh_filename_sanitizer:sanitize`. See below for more details.

### What about already existing files and folders and the links to these?

[](#what-about-already-existing-files-and-folders-and-the-links-to-these)

**IMPORTANT:** The sanitizing rules are applied when saving a file or folder already existing.

#### The file or folder is linked in the system by binary UUID

[](#the-file-or-folder-is-linked-in-the-system-by-binary-uuid)

This is the case if you have used `fileTree` widgets (file pickers) in news or content elements for example. Same applies if you have used inserttags like `{{file::some-hash-uuid}}`.

In this case the links will be working even after the sanitizing has been done because the link is done by an immutable binary UUID stored in the database.

#### The file or folder is linked in the system by a hardcoded path

[](#the-file-or-folder-is-linked-in-the-system-by-a-hardcoded-path)

Files and folders already present in the system

**Caution: Files not linked by UUIDs are DEAD after filename sanitizing has been used.**

You'll have to create htaccess rules to redirect the old paths to the new ones in this case.

#### The file or folder if linked from outside of the system

[](#the-file-or-folder-if-linked-from-outside-of-the-system)

In this case it's of course always a hardcoded path. You'll have to create htaccess rules to redirect the old paths to the new ones in this case.

Commands
--------

[](#commands)

### Sanitize Command

[](#sanitize-command)

This command is designed for sanitizing existing files as a batch processing. Please use it with caution!

Features:

- process files or folders (one or more by passing a pipe ("|") separated list of IDs or paths)
- run as dry-run to see what would have been done if the command is executed
- generate a set of htaccess rules to redirect the old paths to the new ones (pass in a `domain`)

Usage:

```
vendor/bin/contao-console huh_filename_sanitizer:sanitize [options]

```

Options:

```
    --dry-run[=DRY-RUN]      See what the command would do [default: false]
    --ids[=IDS]              Pass in one or a comma separated list of IDs (tl_files.id); example: 1,2,3
    --paths[=PATHS]          Pass in one or a *pipe* separated list of paths (relative to the Contao root directory); example: files|files/some-folder|files/Hello, John
-R, --recursive[=RECURSIVE]  Also process files/folders inside folders [default: false]
    --domain[=DOMAIN]        The domain for the htaccess rewrite rules

```

Events
------

[](#events)

NameArguments`AfterFilenameSanitizationEvent``string $file``AfterFolderSanitizationEvent``string $folder``AfterStringSanitizationEvent``string $string``BeforeFilenameSanitizationEvent``\Contao\File file``BeforeFolderSanitizationEvent``\Contao\Folder $folder``BeforeStringSanitizationEvent``string $string`

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance22

Infrequent updates — may be unmaintained

Popularity25

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity75

Established project with proven stability

 Bus Factor1

Top contributor holds 80% 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 ~119 days

Recently: every ~324 days

Total

20

Last Release

470d ago

Major Versions

1.3.2 → 2.0.02020-01-27

PHP version history (3 changes)1.0.0PHP ^7.1

2.3.0PHP ^7.1|^8.0

2.4.0PHP ^7.4||^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/28ad3224d8727b622ebd229840eea6b9dbcb83eb0bd609e6ce65b614830ff538?d=identicon)[digitales@heimrich-hannot.de](/maintainers/digitales@heimrich-hannot.de)

---

Top Contributors

[![LongDuc89](https://avatars.githubusercontent.com/u/183475641?v=4)](https://github.com/LongDuc89 "LongDuc89 (4 commits)")[![koertho](https://avatars.githubusercontent.com/u/12064642?v=4)](https://github.com/koertho "koertho (1 commits)")

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/heimrichhannot-contao-filename-sanitizer-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/heimrichhannot-contao-filename-sanitizer-bundle/health.svg)](https://phpackages.com/packages/heimrichhannot-contao-filename-sanitizer-bundle)
```

###  Alternatives

[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k17.9M388](/packages/easycorp-easyadmin-bundle)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

9421.6k61](/packages/open-dxp-opendxp)[contao-community-alliance/dc-general

Universal data container for Contao

1680.8k92](/packages/contao-community-alliance-dc-general)

PHPackages © 2026

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