README

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

Requirements

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('contact@example.com', 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');