elcuro / sulu-slug-replacers

v1.0.0 2026-10-29 16:05 UTC

Requires

• php: ^8.2
• symfony/config: ^5.4 || ^6.4 || ^7.0 || ^8.0
• symfony/dependency-injection: ^5.4 || ^6.4 || ^7.0 || ^8.0
• symfony/http-kernel: ^5.4 || ^6.4 || ^7.0 || ^8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^10.5 || ^11.0 || ^12.0

Suggests

• sulu/sulu: Supported versions: ^2.5 and ^3.0

MIT

• Juraj Jancuska

• slug
• transliteration
• sulu
• resource-locator

Published on Packagist.org on 2026-10-29 16:11 UTC

README

Configure the character replacements Sulu applies when it generates URL slugs (resource locators) from page titles.

Sulu ships a hard-coded replacer table that transliterates umlauts the German way for every locale: ä → ae, ö → oe, ü → ue. For languages such as Slovak, Czech, Finnish or Estonian the expected result is simply ä → a. This bundle lets you override any of those replacements — globally or per locale — via Symfony configuration, without patching the vendor code.

Works with Sulu 2.5+ and Sulu 3.x.

Installation

composer require elcuro/sulu-slug-replacers

Register the bundle if Symfony Flex did not do it for you:

// config/bundles.php
return [
    // ...
    Elcuro\SuluSlugReplacersBundle\SuluSlugReplacersBundle::class => ['all' => true],
];

Configuration

# config/packages/sulu_slug_replacers.yaml
sulu_slug_replacers:
    replacers:
        # applied to every locale
        default:
            ä: a
            Ä: A
        # per-locale overrides win over "default" (same semantics as Sulu's replacers.xml)
        de:
            ä: ae
            Ä: Ae

Only the keys you configure are changed; every other replacement Sulu defines stays in place. Replacements run before the Symfony slugger, so the value should already be ASCII (it is slugified and lower-cased afterwards anyway).

Only newly generated slugs are affected — existing routes are not rewritten.

How it works

A compiler pass (priority -10, so it runs after Sulu's own ReplacersCompilerPass) merges the configured map into Sulu's path cleanup service:

Sulu	Service	Where the replacers come from
2.x	sulu.content.path_cleaner	$replacers argument, loaded from replacers.xml
3.x	sulu_route.path_cleanup	constructor default (PathCleanupInterface::DEFAULT_REPLACERS)

The pass reads the current value from whichever of the two applies, overrides the configured keys and sets the argument explicitly. No Sulu classes are referenced, so the bundle has no hard dependency on a specific Sulu version.

Development

composer install
composer test
composer lint   # phpstan + php-cs-fixer (dry run)
composer fix

License

MIT