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)47.8k[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 1mo 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 40 — FairBetter than 88% of packages Maintenance31 Infrequent updates — may be unmaintained Popularity27 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 416d 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 [sulu/sulu Core framework that implements the functionality of the Sulu content management system 1.3k1.3M152](/packages/sulu-sulu)[prestashop/prestashop PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers. 9.0k15.4k](/packages/prestashop-prestashop)[contao/core-bundle Contao Open Source CMS 1231.6M2.3k](/packages/contao-core-bundle)[ec-cube/ec-cube EC-CUBE EC open platform. 78527.0k1](/packages/ec-cube-ec-cube)[contao/manager-bundle Provides the Contao Managed Edition 181.3M61](/packages/contao-manager-bundle)[netgen/layouts-core Netgen Layouts enables you to build and manage complex web pages in a simpler way and with less coding. This is the core of Netgen Layouts, its heart and soul. 3689.4k10](/packages/netgen-layouts-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)