rjds/php-slugify

A PHP library to convert a string into a clean URL-safe lowercase string.

v2.2.0 2026-03-21 11:19 UTC

Requires

• php: ^8.1
• ext-intl: *

Requires (Dev)

• infection/infection: ^0.27 || ^0.32
• phpro/grumphp: ^1.13 || ^2.0
• phpstan/phpstan: ^1.12 || ^2.0
• phpunit/phpunit: ^10.5 || ^11.0 || ^12.0 || ^13.0
• squizlabs/php_codesniffer: ^3.10 || ^4.0

MIT

• Ruben Eekhof

README

A PHP library to convert a string into a clean URL-safe lowercase string.

Requirements

Requirement	Version
PHP	8.1+
ext-intl	*

Installation

Install from Packagist with Composer:

composer require rjds/php-slugify

Usage

Getting started with php-slugify is simple.

Basic Example

use Rjds\PhpSlugify\SluggerFactory;

$slugger = SluggerFactory::create();

// Outputs: hello-world-2026
echo $slugger->slugify('Hello World 2026!');

Customizing the Divider

You can change the default hyphen to any other character:

// Outputs: hello_world_2026
echo $slugger->slugify('Hello World 2026', '_');

Custom Character Mapping

You can pass an associative array of custom character replacements via the mappings parameter. Mappings are applied before transliteration, enabling domain-specific replacements:

// Outputs: tom-and-jerry
echo $slugger->slugify('Tom & Jerry', mappings: ['&' => 'and']);

// Outputs: contact-at-example-dot-com
echo $slugger->slugify('[e-mail]', mappings: ['@' => ' at ', '.' => ' dot ']);

// Combine with a custom divider
// Outputs: price_10_eur
echo $slugger->slugify('Price 10€', divider: '_', mappings: ['€' => ' eur']);

Language-Aware Transliteration

By default, the slugger uses generic Unicode-to-ASCII transliteration. For languages with specific conventions, pass a locale to SluggerFactory::create():

// German: ü → ue, ö → oe, ä → ae, ß → ss
$slugger = SluggerFactory::create('de');

// Outputs: ueber-die-bruecke
echo $slugger->slugify('Über die Brücke');

// Outputs: strasse
echo $slugger->slugify('Straße');

// Turkish: ı → i, İ → I, ş → s, ç → c, ğ → g
$slugger = SluggerFactory::create('tr');

// Outputs: istanbul
echo $slugger->slugify('İstanbul');

Supported locales: de (German), tr (Turkish).

User-provided mappings override locale mappings when both define the same character:

$slugger = SluggerFactory::create('de');

// Outputs: u-boot (user mapping Ü → U overrides locale Ü → Ue)
echo $slugger->slugify('Ü-Boot', mappings: ['Ü' => 'U']);

Max Length / Truncation

You can limit the slug length with the maxLength parameter. The slug is truncated on a word boundary so words are never cut in half:

// Outputs: the-quick (truncated at word boundary, not "the-quick-bro")
echo $slugger->slugify('The Quick Brown Fox', maxLength: 14);

// Outputs: hello-world (no truncation needed)
echo $slugger->slugify('Hello World', maxLength: 50);

// Combine with a custom divider
// Outputs: hello_world
echo $slugger->slugify('Hello World 2026', '_', maxLength: 15);

Empty Input Handling

By default, an empty string input returns an empty string. You can customize this with the emptyValue parameter:

// Outputs: (empty string)
echo $slugger->slugify('');

// Outputs: n-a
echo $slugger->slugify('', emptyValue: 'n-a');