Делаем slugify для кириллицы

Делаем slugify для кириллицыот таблицы strtr до ICU Transliterator

Из заголовка «Ёлки-палки: 10 советов» нужно получить аккуратный адрес elki-palki-10-sovetov. Сравниваем три способа и разбираем, где каждый подводит.

Раздел
PHP
Стек
PHP 8intlICUsymfony/string
Уровень
Новичок
Опубликовано
Обновлено
Чтение
8 мин
Коротко
  • Своя таблица со strtr предсказуема, но только для русского.
  • iconv TRANSLIT зависит от локали и libc сервера.
  • Transliterator из intl понимает почти любую письменность.
  • Опубликованный слаг меняйте только с редиректом.
Как решаем
  1. Переведите текст в латиницу таблицей или ICU
  2. Приведите строку к нижнему регистру
  3. Замените всё, кроме a-z и 0-9, на дефис
  4. Обрежьте дефисы по краям и длину
  5. Проверьте уникальность и задайте запасной слаг

Зачем вообще транслитерировать#

Адрес статьи вида /blog/kak-nastroit-nginx читается в мессенджере, не превращается в длинную кашу из процентов при копировании и не ломается в старых почтовых клиентах. Кириллица в URL формально допустима, браузеры её покажут, но при вставке в письмо или чат она часто кодируется в %D0%BA%D0%B0.... Поэтому для ЧПУ на русскоязычных сайтах обычно делают «слаг»: латиницу в нижнем регистре, цифры и дефисы.

Функция slugify решает четыре задачи: перевести кириллицу в латиницу, привести к нижнему регистру, заменить всё лишнее на разделитель и обрезать разделители по краям. Почему разделитель именно дефис, а не подчёркивание, мы объясняли в заметке про URL с дефисами в CodeIgniter: поисковики считают дефис границей слов.

Слаг вычисляют один раз, при сохранении записи, и хранят в отдельном столбце базы. Генерировать его на лету из заголовка при каждом запросе плохая идея: любая правка опечатки в заголовке молча поменяет адрес страницы, а поиск записи по слагу превратится в перебор. Отдельный столбец с индексом решает обе проблемы, а заодно позволяет редактору вручную задать короткий адрес, если автоматический получился неудачным.

Классика: своя таблица и strtr#

Самый предсказуемый способ, которым пользовались годами: таблица соответствий и strtr. Функция заменяет подстроки за один проход и всегда выбирает самое длинное совпадение, поэтому порядок ключей не важен.

PHP
<?php
// 2012: своя таблица транслитерации
function slugify($text)
{
    static $map = array(
        'а' => 'a',  'б' => 'b',  'в' => 'v',  'г' => 'g',   'д' => 'd',
        'е' => 'e',  'ё' => 'e',  'ж' => 'zh', 'з' => 'z',   'и' => 'i',
        'й' => 'y',  'к' => 'k',  'л' => 'l',  'м' => 'm',   'н' => 'n',
        'о' => 'o',  'п' => 'p',  'р' => 'r',  'с' => 's',   'т' => 't',
        'у' => 'u',  'ф' => 'f',  'х' => 'h',  'ц' => 'ts',  'ч' => 'ch',
        'ш' => 'sh', 'щ' => 'sch','ъ' => '',   'ы' => 'y',   'ь' => '',
        'э' => 'e',  'ю' => 'yu', 'я' => 'ya',
    );

    $text = mb_strtolower($text, 'UTF-8');
    $text = strtr($text, $map);
    $text = preg_replace('~[^a-z0-9]+~', '-', $text);
    return trim($text, '-');
}

echo slugify('Ёлки-палки: 10 советов по PHP!'); // elki-palki-10-sovetov-po-php

Что здесь важно:

  • mb_strtolower до замены. Обычная strtolower не трогает кириллицу в UTF-8, и таблицу пришлось бы дублировать заглавными буквами.
  • Регулярка без флага u работает здесь корректно: после транслитерации в строке остаются только ASCII-символы и байты непереведённых букв, а они все попадут под [^a-z0-9].
  • trim с дефисом убирает разделители, которые получились из знаков препинания в начале и конце.

Минус подхода в том, что таблица покрывает только русский алфавит. Украинские і, ї, є, казахские буквы, немецкие умляуты и французские акценты превратятся в дефисы, и из заголовка останутся обрывки.

Почему iconv с TRANSLIT ненадёжен#

Второй популярный рецепт: iconv('UTF-8', 'ASCII//TRANSLIT', $text). Для латиницы с диакритикой он часто работает, но результат зависит от окружения, а не только от кода:

PHP
<?php
setlocale(LC_CTYPE, 'en_US.UTF-8');
$ascii = iconv('UTF-8', 'ASCII//TRANSLIT', 'Café crème'); // обычно "Cafe creme"

Проблем три. Во-первых, транслитерация зависит от текущей локали LC_CTYPE: без вызова setlocale на многих серверах вместо букв получаются вопросительные знаки. Во-вторых, она зависит от реализации iconv: glibc в Debian и Ubuntu и musl в Alpine-контейнерах ведут себя по-разному, и код, проверенный локально, может выдавать другой результат в Docker. В-третьих, кириллицу этот способ переводит плохо или не переводит вовсе. Мы не рекомендуем полагаться на iconv для русских заголовков: проще держать таблицу или взять ICU.

Перед тем как переходить на ICU, проверьте, что расширение доступно везде, где работает код: php -m | grep intl на сервере и в образе CI. В официальных Docker-образах PHP его нужно подключить отдельно через docker-php-ext-install intl, и это частая причина, по которой локально всё работает, а в контейнере падает.

Подводные камни любого slugify#

Независимо от способа транслитерации, у функции есть несколько мест, где обычно ошибаются:

СитуацияЧто получитсяЧто делать
Заголовок из одних эмодзи или иероглифовПустая строкаПодставить запасной слаг или id записи
Очень длинный заголовокURL на 200 символовОбрезать по длине и убрать хвостовой дефис
Две статьи с одинаковым заголовкомОдинаковые слагиУникальный индекс в базе и суффикс -2, -3
Заголовок отредактировали после публикацииНовый адрес, старые ссылки ведут в 404Не менять слаг автоматически или хранить редирект со старого

Проверку уникальности делайте запросом с меткой, например SELECT 1 FROM posts WHERE slug = ?, как в нашем разборе подготовленных выражений PDO, и всё равно держите на столбце уникальный индекс: два параллельных сохранения могут пройти проверку одновременно.

Отдельный вопрос: нужно ли выбрасывать из слага короткие служебные слова вроде «и», «в», «на». Адрес станет короче, но иногда потеряет смысл, а «как» и «что» в заголовках-вопросах несут суть. Мы предпочитаем оставлять слова как есть и ограничивать только длину: обрезка по последнему целому слову даёт читаемый результат без словарей стоп-слов, которые придётся поддерживать для каждого языка.

Что изменилось к 2026 году#

Самописная таблица уступила место ICU. Расширение intl входит в стандартные сборки PHP большинства дистрибутивов и образов, а его класс Transliterator умеет переводить в латиницу практически любую письменность. Правила записываются цепочкой через точку с запятой: Any-Latin переводит в латиницу, Latin-ASCII снимает диакритику, Lower() приводит к нижнему регистру.

У чистого Any-Latin для кириллицы есть особенность: он опирается на научную транслитерацию с диакритикой, где «ж» становится «ž», а после Latin-ASCII уже просто «z», то есть совпадает с «з». Для русского текста в ICU есть правило Russian-Latin/BGN, которое даёт привычные сочетания вроде «zh» и «sh». Ставим его первым в цепочке, а Any-Latin оставляем для всего остального:

PHP
<?php
declare(strict_types=1);

final class Slug
{
    private static ?Transliterator $tr = null;

    public static function make(string $text, string $sep = '-', int $max = 80): string
    {
        self::$tr ??= Transliterator::create('Russian-Latin/BGN; Any-Latin; Latin-ASCII; Lower()')
            ?? throw new RuntimeException('ICU transliterator is unavailable');

        // мягкий и твёрдый знак в слаге не нужны
        $text  = preg_replace('~[ьъЬЪ]~u', '', $text);
        $ascii = self::$tr->transliterate($text);
        $slug  = trim(preg_replace('~[^a-z0-9]+~', $sep, $ascii), $sep);

        if (strlen($slug) > $max) {               // режем по границе слова
            $cut  = substr($slug, 0, $max + 1);
            $slug = rtrim(substr($cut, 0, strrpos($cut, $sep) ?: $max), $sep);
        }
        return $slug !== '' ? $slug : 'n-a';
    }
}

Мягкий и твёрдый знак удаляем до транслитерации. Научные и картографические системы передают их апострофами или штрихами, и после замены всех небуквенных символов посреди слова появился бы лишний дефис: вместо pismo получилось бы pis-mo. Объект транслитератора создаём один раз и храним в статическом свойстве: создавать его на каждый вызов незачем. Если create вернул null, значит, в установленной версии ICU нет нужного правила, и лучше упасть сразу, чем тихо выдавать пустые адреса.

В проектах на Symfony или с пакетом symfony/string готовое решение уже есть. AsciiSlugger подбирает правило транслитерации по локали и возвращает объект строки:

PHP
<?php
use Symfony\Component\String\Slugger\AsciiSlugger;

$slugger = new AsciiSlugger('ru');
echo $slugger->slug('Ёлки-палки: 10 советов по PHP!')->lower();

Для полноценной работы ему нужно расширение intl. Во фреймворках слаг обычно живёт рядом с маршрутизацией: в CodeIgniter 4, например, есть хелперы url_title() и mb_url_title(), но переводить кириллицу в латиницу они не умеют, так что транслитерацию делайте до их вызова. Про чистые адреса в этом фреймворке читайте в заметке как убрать index.php, а другие рецепты собраны в разделе PHP.

Какой вариант выбрать#

  1. Только русские заголовки, без зависимостей: своя таблица и strtr. Предсказуемо и одинаково на любом сервере.
  2. Многоязычный контент: Transliterator из intl с цепочкой правил.
  3. Проект на Symfony или с symfony/string: AsciiSlugger, не изобретайте своё.
  4. Любой вариант: покройте функцию тестами на пустую строку, эмодзи, длинный заголовок и буквы «ё», «й», «щ».

И главное правило: однажды опубликованный слаг меняйте только вместе с редиректом. Поисковики и читатели уже запомнили старый адрес.

33буквы в таблице русского алфавита
intlрасширение PHP с классом Transliterator
AsciiSluggerготовый слаггер в symfony/string

«Слаг выглядит мелочью, пока не изменится заголовок и все старые ссылки не начнут вести в 404.»

Главный вывод заметки

Вопросы и ответы

Вопросы и ответы

Можно ли оставить кириллицу в URL?
Можно: браузеры показывают такие адреса нормально, и поисковики их понимают. Но при копировании в чат или письмо они часто превращаются в длинную строку с процентами. Для общих ссылок латинский слаг удобнее, поэтому большинство русскоязычных сайтов выбирают транслитерацию.
Почему iconv возвращает вопросительные знаки?
Транслитерация в iconv зависит от текущей локали и реализации библиотеки на сервере. Без setlocale или на системе, где нет правил для кириллицы, непереводимые символы заменяются знаком вопроса. Надёжнее своя таблица или Transliterator из расширения intl.
Какую систему транслитерации выбрать?
Строгого требования для URL нет. Главное, чтобы слаг читался и не менялся после публикации. Привычные сочетания zh, sh, ch читаются лучше научной записи с диакритикой, поэтому для русского текста удобна своя таблица или правило Russian-Latin/BGN в ICU.
Как сделать слаг уникальным?
Перед сохранением проверьте, занят ли слаг, и добавьте числовой суффикс вроде -2. Одной проверки мало: два параллельных запроса могут пройти её одновременно, поэтому на столбце в базе обязательно нужен уникальный индекс.
Заметка обновлена 12 ноября 2026: код проверен на актуальных версиях, добавлены современные варианты.

Читайте также