README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Dictionary

Многоязычный словарь словоформ для PHP 8.1+: выверенные формы слов (в т.ч. нерегулярные) для 5 языков, поиск по лемме и любой форме, согласование словоформы с количеством (CLDR), числа прописью на 5 языках без ext-intl, толерантный поиск, слияние пользовательских словарей. Нулевые внешние зависимости.

Установка

composer require cloud-castle/dictionary

Требуется PHP 8.1+. Расширения не нужны.

Быстрый старт

<?php

use CloudCastle\Dictionary\Dictionary;
use CloudCastle\Dictionary\Gender;
use CloudCastle\Dictionary\Speller\NumberSpeller;
use CloudCastle\Dictionary\WordClass;

$nouns = Dictionary::load('en', WordClass::Noun);

// Точная форма — включая нерегулярные, где алгоритмы ошибаются.
echo $nouns->formOf('child', 'nom:pl');   // «children»
echo $nouns->formOf('mouse', 'nom:pl');   // «mice»

// Поиск записи по лемме или любой форме.
$entry = $nouns->find('men');             // запись леммы «man»
$entry?->allForms();                      // ['man', 'men']

// Согласование словоформы с количеством (CLDR-правила языка словаря).
$ru = Dictionary::load('ru', WordClass::Noun);
echo $ru->agree(1, 'человек');            // «человек»
echo $ru->agree(2, 'человек');            // «человека»
echo $ru->agree(5, 'человек');            // «человек»  (счётная форма, не «людей»)

// Числа прописью: 5 языков, род, дроби, весь диапазон int — без ext-intl.
echo NumberSpeller::for('ru')->spell(21, Gender::Feminine); // «двадцать одна»
echo NumberSpeller::for('ru')->spellDecimal('3,14');        // «три целых четырнадцать сотых»
echo NumberSpeller::for('fr')->spell(80);                   // «quatre-vingts»
echo NumberSpeller::for('es')->spell(21000);                // «veintiún mil»

// Толерантный поиск: регистр и «ё» ↔ «е».
$ru->findLoose('Ребенок')?->lemma;        // «ребёнок»

// Пользовательские словари и слияние (пользовательские формы в приоритете).
$custom = Dictionary::fromArray(['app' => ['f' => ['nom:sg' => 'app', 'nom:pl' => 'apps']]]);
$merged = $nouns->merge($custom);

Возможности

5 языков: русский, английский, немецкий, французский, испанский — существительные, глаголы, имена и фамилии.
Выверенные формы (включая нерегулярные): man → men, child → children, crisis → crises, а также русские слова с беглой гласной (отец → отца, угол → угла, любовь → любви) — там, где алгоритмические инфлекторы ошибаются.
Согласование с количеством: agree(5, 'яблоко') → «яблок» по CLDR-правилам языка, включая русские счётные формы («пять человек», не «пять людей»).
Числа прописью на 5 языках без ext-intl: род («двадцать одна»), дроби («три целых четырнадцать сотых»), весь диапазон int включая PHP_INT_MIN.
Поиск по лемме и по любой форме (обратный индекс «форма → лемма») плюс толерантный поиск без учёта регистра и с отождествлением «ё»/«е».
Ленивая загрузка словарей из PHP-файлов data/ (дружелюбно к opcache), кэширование на процесс.
Пользовательские словари из записей/массива + слияние с поставляемыми; экспорт toArray(), итерация записей, JSON-сериализация.
Реализует Countable, IteratorAggregate, JsonSerializable; иммутабельные записи WordEntry.

Подробнее о каждой возможности — в wiki: отдельная страница на фичу с примерами, сравнением с аналогами и диаграммой.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	doctrine	symfony	icanboogie	illuminate	наивно¹	intl²
Многоязычные данные словоформ (несколько языков)	✅	❌	✅	✅	❌	❌	❌
Произвольные грамматические формы по ключу (не только plural)	✅	❌	❌	❌	❌	❌	❌
Обратный поиск: запись по лемме или любой словоформе	✅	❌	❌	❌	❌	❌	❌
Слияние пользовательских словарей с приоритетом	✅	❌	❌	❌	❌	❌	❌
Числа прописью: 5 языков, род, дроби, весь диапазон int	✅	❌	❌	❌	❌	❌	✅
Согласование словоформы с количеством (CLDR: 1 яблоко / 5 яблок)	✅	❌	❌	❌	❌	❌	✅
Толерантный поиск: без учёта регистра и «ё» ↔ «е»	✅	❌	❌	❌	❌	❌	❌
Экспорт, итерация и JSON-сериализация словаря	✅	❌	❌	❌	❌	❌	❌
Русские слова с беглой гласной (отец → отца, угол → угла)	✅	❌	❌	❌	❌	❌	❌
Не требует PHP-расширений и внешних зависимостей	✅	✅	✅	✅	❌	✅	❌
Всего	🏆 10	1	2	2	0	1	2

2. Безопасность и корректность

Свойство	🏆 CloudCastle	doctrine	symfony	icanboogie	illuminate	наивно¹	intl²
Правильная форма: phenomenon → phenomena	✅	❌	✅	❌	❌	❌	❌
Правильная форма: index → indices	✅	✅	❌	✅	✅	❌	❌
Правильная форма: matrix → matrices	✅	✅	❌	✅	✅	❌	❌
Правильная форма: cactus → cacti	✅	✅	✅	❌	✅	❌	❌
Правильная форма: criterion → criteria	✅	✅	✅	❌	✅	❌	❌
Всего	🏆 5	4	3	2	4	0	0

3. Производительность

Образование мн. числа 30 выверенных слов, 40 000 раз (минимум из 4).

Решение	Время (мс)	Итог
🏆 CloudCastle	82,5	быстрейшее среди библиотек
doctrine	87,2	аналог
наивно¹	161,8	базовый уровень (не библиотека)
illuminate	1 098,5	аналог
symfony	2 197,3	аналог
icanboogie	4 422	аналог

4. Потребление памяти

Память самой библиотеки (не процесса): удержание + рабочий пик на 40 000 операций, изолированный процесс, baseline интерпретатора и автолоадера вычтен.

Решение	Пиковая память (KB)	Итог
наивно¹	1	базовый уровень (не библиотека)
🏆 CloudCastle	84	легчайшее среди библиотек
symfony	86	аналог
icanboogie	103	аналог
doctrine	297	аналог
illuminate	1 055	аналог

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

_{Таблица «Корректность форм» построена на реальных вызовах: словарь берёт
выверенную форму из данных и точен на всех словах, тогда как алгоритмические
инфлекторы расходятся на трудных случаях (phenomenon, index, matrix,
cactus, criterion). Взамен алгоритмы умеют образовывать форму любого,
в том числе отсутствующего в данных, слова — чего словарь по своей природе не
делает (см. сильные и слабые стороны ниже).}

Вывод: CloudCastle Dictionary — единственный пакет сравнения, сочетающий словарь выверенных словоформ, согласование с количеством и числа прописью на 5 языках: точные формы, скорость выше быстрейшего инфлектора и спеллера ICU, минимум памяти при нулевых зависимостях.

Сильные и слабые стороны — честно

Сильные стороны:

точность словаря на нерегулярных словах — 100 % (данные, не эвристика);
числа прописью без ext-intl — работает на хостингах без ICU, покрывает весь диапазон int (ICU отказывается от PHP_INT_MAX);
согласование с количеством одной строкой — agree(5, 'яблоко');
нулевые зависимости, ленивые данные, opcache-дружелюбно.

Слабые стороны:

словарь не образует формы слов, которых нет в данных, — для произвольных слов нужен алгоритмический инфлектор (cloud-castle/inflector, doctrine/inflector);
поставляемые словари покрывают нерегулярную лексику, а не весь язык: для полного покрытия подключайте собственные данные через fromArray();
спеллер пишет кардинальные числительные; порядковые («двадцать первый») не поддержаны.

Где применять:

Финтех, документы, отчёты — суммы и количества прописью (spell, spellDecimal), согласованные строки («5 платежей», «21 запись») — agree.
UI/уведомления — правильные формы при счётчиках (agree), «ё»-толерантный поиск пользовательского ввода (findLoose).
Морфологически тяжёлые тексты (ru/de/fr/es) — точные словарные формы там, где англоцентричные инфлекторы ошибаются.
Не подходит: генерация форм произвольной лексики «на лету» — берите алгоритмический инфлектор и словарь вместе (словарь выигрывает на точности, инфлектор — на покрытии).

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Качество: покрытие строк 100 %, Infection MSI 100 % (все мутанты убиты), PHPStan max + strict, Psalm level 1, PHPMD, Deptrac, PSR-12. Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/dictionary
Wiki (страница на каждую фичу): https://gitverse.ru/cloud-castle/dictionary/wiki
История изменений: CHANGELOG.md
Обновление версий: UPGRADING.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия